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Capitolo 




Introduzione 



II manuale Guida alia programmazione descrive gli argomenti, intermedi e evoluti, 
quali la costruzione di database client /server, la scrittura di componenti custom, la 
creazione di applicazioni per Web server Internet e l'inclusione del supporto per 
specif iche standard come SOAP, TCP/IP, COM e ActiveX. La maggior parte delle 
funzioni evolute che supportano lo sviluppo per Web, le tecnologie evolute XML e lo 
sviluppo di database richiedono componenti o wizard che non sono disponibili in 
tutte le versioni di C++Builder 

II manuale Guida alia programmazione presuppone una certa familiarita con l'uso di 
C++Builder e la conoscenza delle tecniche fondamentali di programmazione in 
C++Builder. Per una introduzione alia programmazione in C++Builder e 
all'ambiente di sviluppo integrato (IDE), consultare il manuale Per iniziare e la Guida 
in linea. 

Contenuto del manuale 



Questo manuale e costituito da cinque parti: 

• La Parte I, "Programmazione con C++Builder", descrive come costruire 
applicazioni C++Builder per scopi generici. Vi vengono fornite informazioni 
dettagliate sulle tecniche di programmazione, utilizzabili in qualsiasi applicazione 
C++Builder. Per esempio, vi viene descritto 1+uso di oggetti della Visual 
Component Library (VCL) comuni o della Component Library for Cross-platform 
(CLX), che semplificano la programmazione dell'interfaccia utente, per aspetti 
quali la gestione delle stringhe, la manipolazione del testo, l'implementazione 
delle finestre di dialogo comuni di Windows, le operazioni con elementi grafici, la 
gestione degli errori e delle eccezioni, l'uso di DLL, di Ole Automation e la 
scrittura di applicazioni internazionali. 

Capita di rado che una libreria VCL di C++Builder sia scritta in Object Pascal. 
Tuttavia, ci sono casi in cui cio vale anche per programmi C++Builder. Un capitolo 
sul supporto del linguaggio C++ e sulle librerie VCL descrive alcuni argomenti 
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relativi al linguaggio quali le diverse modalita con cui si istanzia una classe C++ 
quando si utilizzano le classi VCL o le estensioni del linguaggio C++ aggiunte per 
supportare il modello di programmazione "componente-proprieta-evento" di 
C++Builder. 

Un capitolo descrive come utilizzare gli oggetti inclusi nella Borland Component 
Library for Cross-Platform (CLX) per lo sviluppo di applicazioni che possono 
essere compilate ed eseguite su piattaforme Windows o Linux. 

II capitolo sulla distribuzione illustra dettagliatamente le operazioni connesse alia 
distribuzione delle applicazioni agli utenti. Per esempio, include informazioni 
sulle opzioni del compilatore, sull'uso di InstallShield Express, sulla concessione 
delle licenze e su come determinare quali package, DLL e altre librerie utilizzare 
per generare una versione della propria applicazione da immettere sul mercato. 

• La Parte II, "Sviluppo di applicazioni database", descrive come costruire 
applicazioni database utilizzando strumenti e componenti database. C++Builder 
permette di accedere a molti tipi di database, inclusi i database locali come 
Paradox e dBASE e database SQL server per rete come InterBase, Oracle e Sybase. 
E possibile scegliere fra vari meccanismi per l'accesso di dati, fra cui dbExpress, 
Borland Database Engine, Inter BaseExpress e ActiveX Data Objects (ADO). Per 
implementare applicazioni database client /server piu evolute, sono necessarie 
funzionalita di C++Builder che non sono disponibili in tutte le edizioni. 

• La Parte III, "Creazione di applicazioni Internet", descrive come creare 
applicazioni da distribuire in Internet. C++Builder include una vasta gamma di 
strumenti per la scrittura di applicazioni per Web server, fra cui Web Broker, 
un'architettura che permette di creare applicazioni server per piu piattaforme, 
WebSnap, che permette di progettare pagine web in un ambiente GUI, il supporto 
per operazioni con documenti XML, e BizSnap, un'architettura per l'utilizzo di 
Servizi Web basati su SOAP. 

Questa parte contiene anche un capitolo sui componenti socket di C++Builder che 
permettono di creare applicazioni in grado di comunicare con altri sistemi tramite 
TCP/IP e i protocolli correlati. I socket forniscono connessioni basate sul 
protocollo TCP/IP, ma sufficientemente generiche da consentire di lavorare con 
protocolli correlati come Xerox Network System (XNS), DECnet di Digital o la 
famiglia IPX/SPX di Novell. 

• La Parte IV, "Sviluppo di applicazioni COM", descrive come costruire 
applicazioni in grado di interagire con altri oggetti API basati su COM. 
C++Builder supporta le applicazioni COM basate sui wizard ATL (Active 
Template Library) e un Type Library editor per semplificare lo sviluppo di server 
COM, oltre a uno strumento di importazione che consente di creare rapidamente 
applicazioni client. II supporto per i client COM e previsto in tutte le versioni di 
C++Builder. II supporto per i server COM non e disponibile in tutte le versioni di 
C++Builder. 

• La Parte V, "Creazione di componenti custom", descrive come progettare e 
implementare componenti personali e come renderli disponibili nella Component 
palette dell'IDE. Un componente puo essere un qualsiasi elemento di programma 
che si desidera gestire in fase di progettazione. L'implementazione di componenti 
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personalizzati implica la derivazione di una nuova classe a partire da uno dei tipi 
di classe presenti nelle librerie di classi VCL o CLX. 



Convenzioni tipografiche 



II presente manuale utilizza i caratteri e i simboli descritti nella Tabella 1.1 per 
indicare un testo speciale. 

Tabella 1.1 Caratteri tipografici e simboli 
Carattere o simbolo Significato 

Monospaziato II carattere monospaziato viene utilizzato per rappresentare un testo cosi 
come appare sullo schermo o nel codice C++. Rappresenta, inoltre, tutto cio 
che deve essere immesso da tastiera. 

[ ] Le parentesi quadre nel testo o nei listati sintattici racchiudono elementi 
facolativi. Un testo di questo tipo non deve essere scritto letteralmente. 

Grassetto Le parole in grassetto nel testo o nei listati di codice rappresentano parole 
riservate di C++ oppure opzioni del compilatore. 

Corsivo Le parole in corsivo nel testo rappresentano identificatori di C++, come i 
nomi di variabili o di tipi. II corsivo viene anche utilizzato per mettere in 
evidenza determinate parole, come i nuovi termini. 

Keycaps Questo carattere indica un tasto sulla tastiera. Ad esempio, "Premere Esc 
per uscire dal menu". 



Servizi di assistenza agli sviluppatori 



Borland offre diverse opzioni di supporto. Tra queste vi sono servizi gratuiti su 
Internet, dove si possono fare ricerche in un'ampia base di informazioni o collegarsi 
con altri utenti dei prodotti Borland. Inoltre, e possibile scegliere tra varie categorie di 
supporto, che vanno dal supporto all'installazione del prodotto Borland al supporto 
a livello di consulenza e all'assistenza estesa non gratuiti. 

Per ottenere informazioni sui costi dei servizi Borland di assistenza agli sviluppatori, 
visitare il sito Web di Borland, all'indirizzo http:/ /www .borland.com/devsupport/ 
bcppbuilder, oppure all'indirizzo htpp:/ /www .borland.it (seguire i collegamenti a 
Borland Assist), oppure contattare telefonicamente Borland Assist al numero 
0542.34058. 1 clienti non residenti negli Stati Uniti d' America possono anche 
consultare il sito web di Borland all'indirizzo http:/ /www .borland.com/bww/ 
intlcust.html. 

Quando si contatta il supporto tecnico, e bene avere sotto mano tutte le informazioni 
relative all'ambiente, alia versione del prodotto utilizzato e una descrizione 
dettagliata del problema. 

Come ordinare la documentazione cartacea 



Per ordinare la documentazione aggiuntiva, visitare il sito http:/ /shop .borland.com. 
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Programmazione con C++Builder 

I capitoli inclusi nella sezione "Programmazione con C++Builder" illustrano i 
concetti di base e le nozioni necessarie per creare applicazioni C++Builder con 
qualunque edizione del prodotto. 



Programmazione con C + + Builder 



Capitolo 




Sviluppo di applicazioni con 

C++Builder 

Borland C++Builder e un ambiente di programmazione visuale orientato agli oggetti 
per lo sviluppo di applicazioni a 32-bit da distribuire in ambiente Windows e Linux. 
Con C++Builder e possibile creare applicazioni ad elevata efficienza scrivendo 
pochissime righe di codice. 

C++Builder mette a disposizione una suite di strumenti di progettazione RAD 
(Rapid Application Development) che include wizard per la programmazione oltre a 
modelli di applicazioni e schede, e supporta la programmazione orientata agli 
oggetti grazie a una completa libreria di classi: 

• la Visual Component Library (VCL), che include oggetti che, oltre alle API di 
Windows, incapsulano molte altre utili tecniche di programmazione (Windows). 

• la Borland Component Library for Cross-Platform (CLX), che include oggetti che 
incapsulano la libreria Qt (Windows o Linux). 

Questo capitolo descrive in breve l'ambiente di sviluppo di C++Builder e come esso 
si adatta perfettamente al ciclo di sviluppo di un progetto. Nella parte rimanente di 
questo manuale vengono forniti dettagli tecnici sullo sviluppo di applicazioni 
generiche, di applicazioni database, di applicazioni Internet e Intranet, oltre che sulla 
scrittura di controlli ActiveX e COM e di componenti personali. 

Ambiente di sviluppo integrate 



Quando si avvia C++Builder, ci si trova immediatamente all'interno dell'ambiente di 
sviluppo integrate), detto anche IDE. Questo ambiente fornisce tutti gli strumenti 
necessari per progettare, sviluppare, collaudare, correggere e distribuire le 
applicazioni, consentendo cosi la creazione rapida di prototipi e l'abbreviazione dei 
tempi del ciclo di sviluppo. 
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Progettazione di applicazioni 

L'IDE include tutti gli strumenti necessari per iniziare la progettazione di 
applicazioni, quali: 

• Form Designer, una finestra vuota, detta anche scheda, in cui progettare 
l'interfaccia utente (UI) dell'applicazione. 

• Component palette per la visualizzazione di componenti visuali e non, che e 
possibile utilizzare per progettare l'interfaccia utente. 

• Object Inspector per esaminare e modificare le proprieta e gli eventi degli oggetti. 

• Object Tree View per visualizzare e modificare le relazioni di un componente. 

• Code editor per la stesura e la modifca della logica sottostante di un programma. 

• Project Manager per gestire i file che costituiscono uno o piu progetti. 

• Debugger integrato per ricercare e corregere gli errori nel codice. 

• Molti altri strumenti, come gli editor di proprieta per modificare i valori delle 
properieta di un oggetto. 

• Strumenti per la riga comandi che comprendono compilatori, linker e altri 
programmi di utilita. 

• Complete librerie di classi con moltissimi oggetti riutilizzabili. La maggior parte 
degli oggetti forniti nella libreria di classi sono accessibili nell'IDE dalla 
Component palette. Per convenzione, i nomi degli oggetti nella libreria di classi 
iniziano con una T, come TStatusBar. 

Alcuni strumenti potrebbero non essere inclusi in tutte le edizioni del prodotto. 

Nel manuale Per iniziare, incluso nel prodotto, viene presentata una panoramica piu 
completa sull'ambiente di sviluppo. Inoltre, il sistema di Guida in linea contiene la 
descrizione completa dei menu, delle finestre di dialogo e delle finestre 
dell'applicazione. 

Progettazione di applicazioni 



C++Builder puo essere usato per progettare qualsiasi tipo di applicazione a 32 bit — 
dai programmi di utilita per scopi generici ai sofisticati programmi di accesso ai dati 
o applicazioni distribuite. 

Quando si progetta in modo visuale l'interfaccia utente per l'applicazione, 
C++Builder genera il codice C++ sottostante. Quando si selezionano e si modificano 
le proprieta di componenti e schede, i risultati di queste modifiche vengono 
visualizzati automaticamente nel codice sorgente e viceversa. E possibile modificare i 
file sorgente direttamente con qualsiasi editor di testo, compreso il Code editor 
integrato. Le modifiche apportate vengono immediatamente riportate nell'ambiente 
visuale. 

In C++Builder e possibile creare dei propri componenti. La maggior parte dei 
componenti forniti e scritta in Object Pascal. E possibile aggiungere alia Component 
palette i propri componenti oppure personalizzarla in base alle proprie preferenze 
inserendo, ad esempio, nuove pagine. 

Utilizzando la libreria CLX e possibile anche utilizzare C++Builder per lo sviluppo di 
applicazioni eseguibili su entrambe le piattaforme Linux e Windows. CLX contiene 
un insieme di classi che, se utilizzate al posto di quelle incluse nella VCL, permettono 
di eseguire il porting del programma tra Windows e Linux. Per i dettagli sulla 
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Creazione di progetti 

programmazione per piu piattaforme e per le differenze fra gli ambienti Windows e 
Linux, fare riferimento al Capitolo 14, "Sviluppo di applicazioni multipiattaforma". 

II Capitolo 7, "Creazione di applicazioni, componenti e librerie", presenta i supporti 
forniti da C++Builder per i diversi tipi di applicazioni. 

Creazione di progetti 



In C++Builder, tutte le attivita relative alio sviluppo di applicazioni ruotano intorno 
ai progetti. Quando si crea un'applicazione in C++Builder si crea un progetto. Un 
progetto e una raccolta di file che compongono un'applicazione. Alcuni di questi file 
sono creati in fase di progettazione. Gli altri vengono generati automaticamente 
quando si compila il codice sorgente del progetto. 

E possibile visualizzare il contenuto di un progetto in uno strumento per la gestione 
dei progetti di nome Project Manager. II Project Manager elenca, in una vista 
gerarchica, i nomi delle unit, le schede contenute nella unit (nel caso ve ne siano) e 
mostra i percorsi dei file nel progetto. Benche sia possibile modificare direttamente la 
maggior parte di questi file, spesso e piu semplice e affidabile utilizzare gli strumenti 
visuali di C++Builder. 

In cima alia gerarchia del progetto, vi e un file di gruppo. E possibile combinare piu 
progetti in un gruppo di progetti. Cio permette di aprire nel Project Manager piu di 
un progetto per volta. I gruppi di progetti permettono organizzare e operare su 
progetti correlati, come le applicazioni che funzione in combinazione fra di loro o che 
fanno parte di un'applicazione multi-tier. Se si lavora su un solo progetto, per creare 
un'applicazione non e necessario un file di gruppo di progetti. 

I file di progetto, che descrivono i singoli progetti, i file e le opzioni associate, hanno 
l'estensione .bpr. I file di progetto contengono indicazioni per la generazione di 
un'applicazione o di un oggetto condiviso. Quando si aggiungono e rimuovono file 
utilizzando il Project Manager, il file di progetto viene aggiornato. Le opzioni di 
progetto vengono specificate utilizzando una finestra di dialogo, Project Options, 
contenente varie pagine per i diversi aspetti del progetto come le schede, 
l'applicazione o il compilatore. Queste opzioni di progetto vengono memorizzate nel 
file di progetto assieme al progetto. 

Le unit e le schede sono i componenti di base di un'applicazione in C++Builder. Un 
progetto puo condividere tutti i file form e unit esistenti, inclusi quelli che risiedono 
esternamente all'albero delle directory di progetto. Questo include le procedure e le 
funzioni custom che sono state scritte come routine indipendenti. 

Se si aggiunge a un progetto un file condiviso, e bene rendersi conto che il file non 
viene copiato nella directory del progetto corrente; rimane nella sua ubicazione 
attuale. L'aggiunta al progetto corrente di un file condiviso registra il nome del file e 
il percorso nel file di progetto. C++Builder gestisce automaticamente questa 
operazione non appena si aggiungono delle unit a un progetto. 

Quando si compila un progetto, non e importate la posizione in cui risiedono i file 
che compongono il progetto. II compilatore tratta i file condivisi esattamente come 
quelli creati dal progetto stesso. 
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Editing del codice 



II Code editor di C++Builder e un editor ASCII completo di ogni funzione. Se si 
utilizza l'ambiente di programmazione visuale, viene visualizzata automaticamente 
una scheda come parte di un nuovo progetto. E possibile cominciare a progettare 
l'interfaccia dell'applicazione collocando oggetti sulla scheda e modificandone il 
funzionamento con l'Object Inspector. Altre attivita di programmazione, invece, 
come la scrittura dei gestori di evento degli oggetti, devono essere fatte immettendo 
il codice. 

I contenuti della scheda, tutte le sue proprieta, i suoi componenti e le rispettive 
proprieta possono essere visualizzati e modificati sotto forma di testo nel Code 
Editor. Nel Code Editor e possibile adattare il codice generato e aggiungervi altri 
componenti dall'interno dell'editor scrivendo il codice opportune Man mano che si 
scrive il codice nell'editor, il compilatore scandisce costantemente ogni modifica e 
aggiorna la scheda con il nuovo layout. E possibile quindi ritornare alia scheda, 
visualizzarla e verificare le modifiche apportate nell'editor, e quindi continuarne la 
messa a punto. 

I sistemi di generazione del codice e di esposizione delle proprieta di C++Builder 
possono essere ispezionati completamente. II codice sorgente per tutto cio che e 
incluso nel file eseguibile finale — vale a dire tutti gli oggetti VCL, tutti gli oggetti 
CLX, i sorgenti RTL e tutti i file di progetto-possono essere visualizzati e modificati 
nel Code editor. 

Compilazione di applicazioni 



Una volta terminata la progettazione sulla scheda dell'interfaccia dell'applicazione e 
la scrittura di tutto il codice aggiuntivo, in modo che l'applicazione faccia cio che ci si 
era prefissi, e possibile compilare il progetto dall'IDE o dalla riga comandi. 

Tutti i progetti hanno come destinazione un singolo file eseguibile distribuibile. E 
possibile visualizzare o provare l'applicazione a diversi stadi dello sviluppo 
compilandola, rigenerandola o mandandola in esecuzione: 

• Quando si compila, vengono ricompilate solo le unit che sono state modificate 
rispetto all'ultima compilazione. 

• Quando si rigenera l'applicazione, vengono ricompilate tutte le unit nel progetto, 
indipendentemente dal fatto che siano state modificate o meno rispetto all'ultima 
compilazione. E importante utilizzare il comando Build anche quando si sono 
modificate le direttive globali del compilatore, in modo da accertarsi che tutto il 
codice venga compilato in base alle impostazioni appropriate. E importante anche 
eseguire la rigenerazione del progetto una volta modificate tutte le direttive 
globali del compilatore per accertarsi che tutto il codice venga compilato nello 
stato opportune E anche possibile verificare la validita del codice sorgente senza 
tentare di compilare il progetto. 
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• Quando si esegue l'applicazione, l'applicazione viene compilata e quindi eseguita. 
Se si e modificato il codice sorgente rispetto all'ultima compilazione, il 
compilatore ricompila i moduli modificati e ne riesegue il link all'applicazione. 

Nel caso si siano raggruppati piu progetti, e possibile compilare o rigenerare in una 
sola volta tutti i progetti in un singolo gruppo di progetti. Dopo aver selezionato nel 
Project Manager il gruppo di progetti, scegliere il comando Project I Compile All 
Projects o Project I Build All Projects. 

Non e ancora disponibile un'applicazione C++ per Linux per compilare 
un'applicazione CLX in Linux, ma e possibile cominciare a sviluppare da ora le 
proprie applicazioni con C++Builder. 

Debug di applicazioni 



C++Builder fornisce un debugger integrato che consente di trovare e di correggere 
gli errori presenti nelle applicazioni. II debugger integrato permette di controllare 
l'esecuzione del programma, di tenere sotto controllo i valori delle variabili e gli 
elementi delle strutture di dati, oltre che di modificare i valori dei dati durante la fase 
di debug. 

II debugger integrato puo tracciare sia gli errori di esecuzione sia gli errori di logica. 
Eseguendo il programma fino a determinati punti ed esaminando i valori delle 
variabili, le funzioni nello stack delle chiamate e l'output del programma, e possibile 
controllare il comportamento del programma e trovare le aree in cui il 
comportamento non e quello progettato. II debugger e descritto nella Guida in linea. 

E anche possibile usare la gestione delle eccezioni per riconoscere, individuare e 
trattare gli errori. In C++Builder le eccezioni sono classi, identiche alle altre classi di 
C++Builder, tranne per il fatto che, per convenzione, il loro nome inizia con una E 
invece che con una T. Per maggiori informazioni sulla gestione delle eccezioni, 
consultare il Capitolo 12, "Gestione delle eccezioni". 

Distribuzione di applicazioni 



C++Builder include strumenti aggiuntivi che consentono la distribuzione delle 
applicazioni. Ad esempio, InstallShield Express (non disponibile in tutte le edizioni) 
aiuta a creare un package per l'installazione dell'applicazione, che include tutti i file 
necessari per l'esecuzione di un'applicazione distribuita. E disponibile anche il 
software TeamSource (non disponibile in tutte le edizioni) per tenere traccia degli 
aggiornamenti apportati alle applicazioni. 

Non tutte le edizioni di C++Builder consentono la distribuzione di applicazioni. 



Non e ancora disponibile un'applicazione C++ per Linux per distribuire 
un'applicazione CLX in Linux, ma e possibile cominciare a sviluppare da ora le 
proprie applicazioni con C++Builder. 
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Distribuzione d i applicazioni 

Per informazioni specifiche sulla distribuzione, consultare il Capitolo 17, 
"Distribuzione di applicazioni",. 
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Capitolo 




Uso delle librerie di 



classi 



Questo capitolo presenta una panoramica delle librerie di componenti e presenta 
alcuni oggetti che e possibile utilizzare durante lo sviluppo di applicazioni. 
C++Builder include sia la Visual Component Library (VCL) che la Borland 
Component Library for Cross-Platform (CLX). La VCL e per lo sviluppo in Windows 
e la CLX e per lo sviluppo multipiattaforma in Windows e in Linux. Sono due librerie 
di classi diverse ma hanno molte somiglianze. 



VCL e CLX sono librerie di classi composte da oggetti che si utilizzano durante lo 
sviluppo di applicazioni. Le librerie sono fra loro simili e contengono entrambe quasi 
tutti gli stessi oggetti. Alcuni oggetti nella VCL implementano funzioni che sono 
disponibili solo in Windows, come gli oggetti che vengono visualizzati sulle pagine 
ADO, BDE, QReport, COM+ e Server della Component palette. Potenzialmente tutti 
gli oggetti CLX sono disponibili sia in Windows che in Linux. 

Tutti gli oggetti della VCL e della CLX discendono da TObject, una classe astratta i cui 
metodi ne definiscono il comportamento di base come la costruzione, la distruzione e 
la gestione dei messaggi. Quando si scrivono personalmente delle classi, dovrebbero 
discendere da TObject incluso nella libreria di classi che si intende utilizzare. 

I componenti sono un sottoinsieme della VCL o della CLX e discendono dalla classe 
astratta TComponent. I componenti sono oggetti che possono essere collocati su una 
scheda o in un modulo dati e trattare in fase di progettazione. La maggior parte dei 
componenti sono visuali o non visuali, a seconda del fatto che siano visibili o meno in 
esecuzione. Alcuni componenti vengono visualizzati nella Component palette. 

I componenti visuali, come TForm e TSpeedButton, sono detti controlli e discendono 
da TControl. TControl fornisce le proprieta che specificano gli attributi visuali dei 
controlli, come la loro altezza e ampiezza. 



Le librerie di classi 
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I componenti non visuali vengono usati per una vasta gamma di compiti. Ad 
esempio, se si sta scrivendo un'applicazione che si connete a un database, e possibile 
collocare sulla scheda un componente TDataSource per collegarsi a un controllo e un 
componente dataset usato dal controllo. Questa connessione non e visibile all'utente, 
pertanto TDataSource non e visuale. In progettazione, i componenti non visuali 
vengono rappresentati da un'icona. Cio consente di manipolarne le proprieta e gli 
eventi esattamente come se si trattasse di un controllo visuale. 

Durante la programmazione, e possibile accedere alia Guida in linea che contiene la 
documentazione di riferimento molto dettagliata su tutti gli oggetti della VCL e della 
CLX. Dall'interno del Code editor, collocare il cursore sull'oggetto e premere Fl per 
visualizzare la Guida sui componenti della topic . Gli oggetti, le proprieta, i metodi e 
gli eventi che sono inclusi nella VCL sono contrassegnati come "VCL Reference", 
mentre quelli inclusi nella CLX come "CLX Reference". 

Proprieta, metodi ed eventi 



Sia la VCL che la CLX sono gerarchie di oggetti legate all'IDE di Delphi, in cui e 
possibile sviluppare rapidamente applicazioni. Gli ogggetti in entrambe le librerie di 
componenti si basano su proprieta, metodi ed eventi. Ogni oggetto include i membri 
dati (le proprieta), le funzioni che operano sui dati (i metodi) e un modo per 
interagire con gli utenti della classe (gli eventi). La VCL e la CLX sono scritte in 
Object Pascal, anche se la VCL si basa sulle API di Windows API e la CLX si basa 
sulla libreria di widget Qt. 

Proprieta 

Le proprieta sono le caratteristiche di un oggetto che influiscono o sui comportamento 
visibile o sulle operazioni dell'oggetto. Ad esempio, la proprieta Visible determina se 
un oggetto puo essere visualizzato o meno nell'interfaccia dell'applicazione. 
Proprieta ben progettate consentono di semplificare l'utilizzo del componente da 
parte di altri programmatori e la manutenzione da parte di chi l'ha progettato. 

Di seguito sono riportare alcune utili caratteristiche delle proprieta: 

• A differenza dei metodi, che sono disponibili solo in esecuzione, e possibile vedere 
e modificare le proprieta nell'IDE in fase di progettazione e ottenere un immediato 
riscontro visivo dei cambiamenti apportati. 

• E possibile accedere alle proprieta tramite l'Object Inspector, che consente di 
modificare visivamente i valori dell'oggetto. L'impostazione delle proprieta in 
fase di progettazione e piu semplice della scrittura del codice e rende il codice piu 
semplice da gestire. 

• Poiche i dati sono incapsulati, risultano protetti e privati all'interno dell'oggetto. 

• Le chiamate volte a ottenere e a impostare i valori sono metodi, rendendo pertanto 
invisibili all'utente dell'oggetto particolari elaborazioni. Ad esempio, i dati 
potrebbero risiedere in una tabella, ma potrebbero apparire al programmatore 
come normali membri dati. 
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• E possibile implementare la logica che innesca eventi o modifica altri dati durante 
l'accesso alia proprieta. Ad esempio, la modifica del valore di una proprieta 
potrebbe richiedere la modifica di un'altra. E possibile modificare i metodi creati 
per la proprieta. 

• Le proprieta possono essere virtuali. 

• Una proprieta non e limitata a un singolo oggetto. La modifica di una proprieta di 
un oggetto potrebbe ripercuotersi su numerosi oggetti. Ad esempio, 
l'impostazione della proprieta Checked su un pulsante di opzione influenza tutti i 
pulsanti di opzione nel gruppo. 

Metodi 

Un metodo e una funzione che e memebro di una classe. I metodi definiscono il 
comportamento di un oggetto. I metodi di classe possono accedere a tutte le 
proprieta pubbliche, protette e private e ai membri dati della classe e sono 
comunemente menzionati come funzioni membro. Consulatre "Controllo 
dell'accesso" a pagina 46-4. 

Eventi 

Un evento e un'azione o un accadimento rilevato da un programma. Molte 
applicazioni moderne vengono definite event-driven, perche sono progettate per 
rispondere agli eventi. In un programma, il programmatore non ha alcun modo di 
prevedere la sequenza esatta di azioni che sara eseguita dall'utente. L'utente ad 
esempio potra scegliere una voce di menu, fare clic su un pulsante o selezionare del 
testo. II programmatore potra scrivere il codice per gestire gli eventi che ritiene 
importanti, invece di scrivere del codice che sara eseguito sempre secondo lo stesso 
ordine limitato. 

Indipendentemente da come e stato chiamato l'evento, C++Builder cerca di 
individuare se e stato predisposto un qualsiasi codice per gestire quel determinato 
evento. Nel caso sia stato predisposto, quel codice viene eseguito; altrimenti, ha 
luogo il comportamento predefinito di gestione dell'evento. 

I tipi di eventi che possono verificarsi possono essere suddivisi in due categorie 
principali: 

• Eventi utente 

• Eventi di sistema 

Eventi utente 

Gli eventi utente sono azioni che vengono iniziate dall'utente. Esempi di eventi 
utente sono OnClick (l'utente ha fatto clic col mouse), OnKeyPress (l'utente ha 
premuto un tasto sulla tastiera), e OnDblClick (l'utente ha fatto doppio clic su un 
pulsante del mouse). 

Eventi di sistema 

Gli eventi di sistema sono eventi generati automaticamente dal sistema operativo. Ad 
esempio, l'evento OnTimer (il componente TTimer genera uno di questi eventi ogni 
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volta che e trascorso un intervallo temporale predefinito), l'evento OnCreate (il 
componente sta per essere creato), l'evento OnPaint (un componente o una window 
devono essere ridisegnati), e cosi via. Di solito, gli eventi di sistema non vengono 
avviati direttamente da un'azione deU'utente. 

Oggetti, componenti e controlli 

La Figura 3.1 mostra in modo molto semplificato la gerarchia dell'ereditarieta che 
illustra le relazioni esistenti tra oggetti, componenti e controlli. 

Figura 3.1 Oggetti, componenti e controlli 




Ogni oggetto eredita da TObject, e molti oggetti ereditano da TComponent. I controlli, 
che ereditano da TControl, hanno la capacita di visualizzare se stessi in fase di 
esecuzione. Un controllo come TCheckBox eredita tutta le funzionalita di TObject, di 
TComponent e di TControl e aggiunge proprie capacita specializzate. 

La Figura 3.2 e una panoramica della Visual Component Library (VCL) che mostra i 
rami principali dell'albero dell'ereditarieta. A questo livello, la Borland Component 
Library for Cross-Platform (CLX) e molto simile, ma TWinControl e sostituito da 
TWidgetControl. 



3-4 Guida alia programmazione 



Oggetti, componenti e controlli 



Figura 3.2 Un diagramma semplificato della gerarchia 
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Nella figura vengono visualizzate diverse importanti classi base che sono descritte 
nella tabella seguente: 

Tabella 3.1 Classi di base importanti 



TObject Indica la classe di base e l'antenato piu remoto di tutto cio che e incluso nella 

VCL o nella CLX. TObject incapsula il comportamento fondamentale comune 
a tutti gli oggetti della VCL/ CLX introducendo i metodi che eseguono le 
funzioni di base come la creazione, la gestione e la distruzione di un'istanza 
di un oggetto. 

Exception Specifica la classe di base di tutte le classi correlate alle eccezioni. La classe 

Exception fornisce un'interfaccia coerente per le condizioni di errore e 
permette alle applicazioni di gestire le condizioni di errore in modo elegante. 

TPersistent Specifica la classe di base per tutti gli oggetti che implementano proprieta. Le 

classi sotto TPersistent si occupano dell'invio di dati agli stream e permettono 
l'assegnazione di classi. 

TComponent Specifica la classe di base per tutti i componenti non visuali come 

T Application. TComponent e l'antenato comune di tutti i componenti. Questa 
classe permette a un componente di essere visualizzato sulla Component 
palette, consente a un componente di possedere altri componenti, e consente 
di trattare il componente direttamente su una scheda. 

TControl Rappresenta la classe di base per tutti i controlli visibili in fase di esecuzione. 

TControl e l'antenato comune di tutti i componenti visuali e fornisce ai 
controlli proprieta standard come posizione e cursore. Questa classe fornisce 
anche gli eventi che rispondono alle azioni del mouse. 

TWinControl Specifica la classe di base di tutti gli oggetti dell'interfaccia utente. I controlli 

sotto TWinControl sono controlli basati su finestre in grado di catturare 
l'input da tastiera. In CLX, questi vengono chiamati widget, e TWidgetControl 
sostituisce TWinControl. 



Le prossime sezioni presentano una descrizione generale dei tipi di classi conytenuti 
in ogni ramo. Per una panoramica completa della gerarchia degli oggetti della VCL e 
della CLX, fare riferimento ai diagramma VCL Object Hierarchy e CLX Object 
Hierarchy inclusi nel prodotto. 
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II ramo TObject 



II ramo TObject include tutti gli oggetti VCL e CLX che discendono da TObject ma 
non da TPersistent. Molte potenti capacita degli oggetti della VCL e della CLX 
derivano dai metodi introdotti da TObject. TObject incapsula il comportamento di 
base comune a tutti gli oggetti della VCL e della CLX, introducendo metodi che 
forniscono: 

• La capacita di rispondere quando gli oggetti vengono creati o distrutti. 

• Tipo della classe e informazioni sull'istanza relativamente a un oggetto, e 
informazioni di tipo in esecuzione (RTTI) relativamente alle proprieta rese 
pubbliche. 

• Supporto per la gestione di messaggi (VCL) oppure per gli eventi di sistema 
(CLX). 

TObject e l'antenato diretto di molte classi semplici. Le classi all'interno del ramo 
TObject hanno un'importante caratteristica comune: sono transitorie. Cio significa 
che queste classi non hanno un metodo per salvare lo stato in cui sono prima di 
essere distrutte, vale a dire che non sono persistenti. 

Uno dei gruppi principali delle classi in questo ramo e la classe Exception. Questa 
classe fornisce una vasta serie di classi di eccezioni predefinite per gestire 
automaticamente errori di divisione per zero, errori di 1/ O su file, conversioni di tipo 
non valide e molte altre condizioni di eccezione. 

Un altro tipo di classe nel ramo TObject sono le classi che incapsulano strutture dati, 
come: 

• TBits, una classe che memorizza un "array" di valori booleani. 

• TList, una classe di lista collegata. 

• TStack, una classe che mantiene un array di puntatori di tipo last-in-first-out. 

• TQueue, una classe che mantiene un array di puntatori di tipo first-in first-out. 

Nella VCL e possibile anche trovare dei wrapper per oggetti esterni come TPrinter, 
che incapsula l'interfaccia per la stampante Windows e TRegistry, un wrapper a basso 
livello per il file di registro di sistema e per le funzioni che operano sul file di registro. 
Queste sono specifiche per l'ambiente Windows. 

TStream e un buon esempio di un altro tipo di classi in questo ramo. TStream e il tipo 
di classe base per oggetti stream che sono in grado di leggere o scrivere su vari tipi di 
supporto, come file su disco, memoria dinamica, e cosi via. 

Pertanto, questo ramo include molti tipi di classi differenti che risultano molto utili 
agli sviluppatori. 

II ramo TPersistent 



II ramo TPersistent include tutti gli oggetti VCL e CLX che discendono da TPersistent 
ma non da TComponent. La persistenza determina che cosa viene salvato con un file 
form o con un modulo dati e che cosa viene caricato nella scheda o nel modulo dati 
quando li si ricupera dalla memoria. 
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Gli oggetti in questo ramo implementano le proprieta per i componenti. Le proprieta 
vengono caricate e salvate con una scheda solo se hanno un possessore. II possessore 
deve essere qualche componente. Questo ramo introduce la funzione GetOwner che 
permette di determinare il possessore della proprieta. 

Gli oggetti in questo ramo sono anche i primi a includere una sezione published in 
cui e possibile caricare e salvare automaticamente le proprieta. II metodo 
DefineProperties permette anche di indicare come caricare e salvare le proprieta. 

Di seguito sono elencate alcune altre classi incluse nel ramo TPersistent della 
gerarchia: 

• TGraphicsObject, una classe base astratta per oggetti grafici, come TBrush, TFont, e 
TP en. 

• TGraphic, una classe base astratta per oggetti come TBitmap e TIcon ,in grado di 
memorizzare e visualizzare immagini. 

• TStrings, una classe base per oggetti che rappresentano un elenco di stringhe. 

• TClipboard, una classe in grado di contenere testo o immagini grafiche tagliate o 
copiate da un'applicazione. 

• T Collection, TOwnedCollection, e TCollectionltem, classi che contengono raccolte 
indicizzate di elementi definiti in modo particolare. 

II ramo TComponent 



II ramo TComponent contiene oggetti che scendono da TComponent ma non da 
TControl. Gli oggetti in questo ramo sono componenti che e possibile manipolare 
sulle schede in fase di progettazione. Essi sono oggetti persistenti che possono fare 
quanto segue: 

• Essere visualizzati sulla Component palette e modificati nel Form designer. 

• Possedere e gestire altri componenti. 

• Caricare e salvare se stessi. 

Diversi metodi in TComponent regolano il comportamento dei componenti in fase di 
progettazione e quali informazioni vengono salvate con il componente. In questo 
ramo della CLX viene introdotto il concetto di stream. C gestisce automaticamente la 
maggior parte delle operazioni che coinvolgono gli stream. Le proprieta sono 
persistenti se sono state rese pubbliche e le proprieta rese pubbliche sono 
automaticamente soggette alio stream. 

La classe TComponent introduce anche il concetto di possesso che e propagato in tutta 
la VCL e la CLX. Due proprieta supportano il possesso: Owner e Components. Ogni 
componente ha una proprieta Owner che fa riferimento a un altro componente come 
possessore. Un componente puo possedere altri componenti. In questo caso, tutti i 
componenti posseduti sono referenziati nella proprieta Array del componente. 

II costruttore di un componente richiede un singolo parametro che e utilizzato per 
specificare il possessore del nuovo componente. Se il possessore che viene passato 
esiste, il nuovo componente viene aggiunto alia lista Components del possessore. Oltre 
all'utilizzo della lista Components per referenziare i componenti posseduti, questa 
proprieta consente anche la distruzione automatica dei componenti posseduti. Finche 



Uso delle librerie di classi 3-7 



Oggetti, component! e controlli 

il componente ha un possessore, sara distrutto al momenta della distruzione del 
possessore. Ad esempio, poiche TForm e un discendente di TComponent, quando si 
distruggera la scheda saranno distrutti tutti i componenti posseduti dalla scheda e la 
memoria allocata sara liberata. In questo caso si parte dall'assunto che tutti i 
componenti sulla scheda siano in grado di far pulizia di se stessi correttamente nel 
momenta in cui vengono chiamati i rispettivi distruttori. 

Se un tipo di proprieta e un TComponent o un discendente, il sistema di streaming 
crea un'istanza di quel tipo al momenta della sua lettura. Se un tipo di proprieta e 
TPersistent ma non TComponent, il sistema di streaming utilizza l'istanza esistente 
disponibile attraverso la proprieta e legge i valori delle proprieta di quell'istanza. 

Quando si crea un file form (un file utilizzato per memorizzare le informazioni 
relative ai componenti sulla scheda), il Form designer analizza ciclicamente la sua 
matrice di componenti e salva tutti i componenti sulla scheda. Ogni componente "sa" 
come scrivere nello stream (in questo caso, un file di testo) le proprieta che sono state 
modificate. Al contrario, quando si caricano le proprieta dei componenti nel file di 
scheda, il Form designer analizza ciclicamente la sua matrice di componenti e carica 
ogni componente. 

I tipi di classi che troverai in questo ramo includono: 

• TActionList, una classe che conserva un elenco di azioni utilizzate con componenti 
e controlli, come elementi di menu e pulsanti. 

• TMainMenu, una classe che fornisce alle schede una barra di menu e i relativi 
menu a discesa. 

• TOpenDialog, TSaveDialog, TFontDialog, TFindDialog, TColorDialog e cosi via, sono 
classi che rendono disponibili le finestre di dialogo utilizzate piu di frequente. 

• TScreen, una classe che tiene traccia di quali schede e moduli dati sono stati 
istanziati dall'applicazione, qual e scheda attiva, qual e il controllo attivo 
all'interno di quella scheda, le dimensioni e la risoluzione dello schermo, e i 
cursori e i font disponibile utilizzabili dall'applicazione. 

Componenti che non hanno bisogno di un'interfaccia visuale possono essere derivati 
direttamente da TComponent. Per creare uno strumento come un dispositivo TTimer, e 
possibile derivarlo da TComponent. Questo tipo di componente risiede nella 
Component palette, ma esegue funzioni interne a cui si accede mediante codice e non 
viene visualizzato nell'interfaccia utente in fase di esecuzione. 

Nella CLX, il ramo TComponent include anche THandleComponent. Questa e la classe 
di base per i componenti non visuali che richiedono un handle per un oggetto Qt 
sottostante, come le finestre di dialogo e i menu. 

Per i dettagli sull'impostazione delle proprieta, sulla chiamata ai metodi e sulle 
operazioni con gli eventi dei componenti, consultare il Capitolo 5, "Operazioni con 
componenti". 

II ramo TControl 



II ramo TControl e formato da componenti che discendono da TControl ma non da 
TWinControl (TWidgetControl nella CLX). Gli oggetti in questo ramo sono controlli 
che sono oggetti visuali che l'utente dll'applicazione puo vedere e manipolare in 
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esecuzione. Tutti i controlli hanno proprieta, metodi ed eventi in comune che sono 
correlati all'aspetto del controllo, come la posizione, il cursore associato alia finestra 
del controllo (al widget nella CLX), i metodi per colorare o spostare il controllo e gli 
eventi per rispondere alle azioni del mouse. I controlli non possono mai ricevere 
l'input da tastiera. 

Mentre TComponent definisce il comportamento di tutti i componenti, TControl 
definisce il comportamento per tutti i controlli visuali. Cio comprende le routine di 
disegno, gli eventi standard e le relazioni contenuto-contenitore. 

Tutti i controlli visuali condividono alcune proprieta. Benche queste proprieta siano 
ereditate da TControl, esse vengo rese pubbliche, e appaiono pertanto nell'Object 
Inspector, solo per quei componenti per cui sono applicabili. Ad esempio, il 
componente TImage non pubblica la proprieta Color, poiche il suo colore e 
determinate) dairimmagine grafica visualizzata. 

Ci sono due tipi di controlli: 

• Quelli che hanno una propria finestra (o un widget. 

• Quelli che utilizzano la finestra (o il widget) del proprio genitore. 

I controlli che hanno una propria finestra sono detti controlli "con finestra" (VCL) o 
controlli "basati su widget" (CLX) e discendono da TWinControl (TWidgetControl in 
CLX). I pulsanti e le caselle di controllo rientrano in questa categoria. 

I controlli che utilizzano la finestra (o il widget) del genitore sono definiti controlli 
grafici e discendono da TGraphicControl. I controlli immagine ed etichetta rientrano 
in questa categoria. I controlli grafici non posseggono un handle e non possono 
ricevere il fuoco. Poiche un controllo grafico non necessita di un handle, utilizza 
meno risorse di sistema. I controlli grafici devono tracciare se stessi e non possono 
essere genitori di altri controlli. 

Per informazioni sugli altri controlli grafici, vedere "Controlli grafici" a pagina 9-19, 
e per i dettagli sui diversi tipi di controlli consultare il Capitolo 9, "Tipi di controlli". 
Per informazioni su come interagire con i controlli in esecuzione, consultare il 
Capitolo 6, "Uso dei controlli". 

II ramo TWinControl/TWidgetControl 



Nella VCL, il ramo TWinControl include tutti i controlli che discendono da 
TWinControl. TWinControl e la classe di base per tutti i controlli con finestra, che 
sono elementi che si utilizzeranno nell'interfaccia utente di un'applicazione. I 
controlli con finestra sono wrapper di controlli Windows. 

In CLX, TWidgetControl, che sostituisce TWinControl, e la classe base per tutti i 
controlli widget, che sono wrappers di widget. 

I controlli con finestra e i widget: 

• Possono ricevere il fuoco durante la fase di esecuzione di un'applicazione, il che 
significa che possono ricevere l'input da tastiera da parte dell'uiente 
dell'applicazione. A confronto, altri controlli possono solo visualizzare dati. 

• Possono essere genitori di uno o piu controlli figlio. 
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• Hanno un handle, o un identificatore univoco. 

II ramo TWmConfroZ/TwidgetControl include sia i controlli che vengono tracciati 
automaticamente (inclusi TEdit, TListBox, TComboBox, TPageControl, e cosi via) sia i 
controlli custom che devono essere tracciati da C++Builder come TDBNavigator, 
TMediaPlayer (solo nella VCL), TGauge (solo nella VCL). Di solito i discendenti diretti 
di TWinControl/TWidgetControl implementano controlli standard, come i campi di 
editing, le caselle combinate, le caselle di riepilogo o i controlli pagina e, pertanto, 
sanno gia come tracciarsi. 

La classe TCustomControl viene fornita per quei componenti che richiedono un 
handle di finestra ma non incapsulano un controllo standard che include la capacita 
di tracciarsi. Non e necessario preoccuparsi di come i controlli vengono tracciati o di 
come rispondono agli eventi. C++Buider incapsula completamente e 
automaticamnete questo comportamento. 
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Capitolo 

4 

Utilizzo di BaseCLX 



Vi sono molte unit comuni sia alia VCL che alia CLX che forniscono il supporto 
sottostante per entrambe le librerie di componenti. Collettivamente, queste unit 
vengono chiamate BaseCLX. BaseCLX non include nessuno dei componenti 
visualizzati sulla Component palette. Include invece moltissime classi e routine 
globali che vengono usate dai componenti che vengono visualizzati sulla Component 
palette. Queste classi e queste routine sono utilizzabili anche nel codice delle proprie 
applicazioni o durante la scrittura delle proprie classi. 

Le routine globali che compongono la BaseCLX sono anche dette libreria di 
esecuzione. Non confondere queste routine con la libreria di esecuzione del C++. 
Molte di queste eseguono funzioni simili a quelle nella libreria di esecuzione del 
C++, ma possono essere distinte in quanto i nomi delle funzioni iniziano con una 
lettera maiuscola e vengono dichiarate nello header di una unit. 

Le sezioni seguenti trattano molte classi e routine che compongono BaseCLX e ne 
illustrano i possibili utilizzi. Fra questi vi sono: 

• Uso di stream 

• Operazioni con i file 

• Operazioni con i file .ini 

• Operazioni con le liste 

• Operazioni con elenchi di stringhe 

• Operazioni con stringhe 

• Conversione di misure 

• Creazione di spazi di disegno 

Questo elenco di attivita non e esaustivo. La libreria di esecuzione in BaseCLX 
contiene molte routine in grado di eseguire compiti non citati in questa trattazione. 
Fra qyesti vi sono una serie di funzioni matematiche (definite nella unit Math), varie 
routine per operare con valori di data/ora (definiti nelle unit SysUtils e DateUtils) e 
routine per operare con i Variant di Object Pascal (definite nella unit Variants). 
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Uso di stream 



Gli stream sono classi che permettono di leggere e scrivere dati. Essi forniscono 
un'interfaccia comune per la lettura e la scrittura su svariati supporti come memoria, 
stringhe, socket e campi BLOB nei database. Esistono numerose classi stream, che 
discendono tutte da TStream. Ogni classe stream e specifica per un tipo di supporto. 
Ad esempio, TMemoryStream legge o scrive su un'immagine in memoria, TFileStream 
legge o scrive su un file. 

Uso di stream per leggere o scrivere dati 



Le classi stream condividono tutte svariati metodi per la lettura e la scrittura di dati. 
Questi metodi sono distinguibili per il fatto che compiono quanta segue: 

• Restituiscono il numero di byte letti o scritti. 

• Richiedono che sia noto il numero di byte. 

• Generano un'eccezione sull'errore. 

Metodi di stream per lettura e scrittura 

II metodo Read legge dallo stream un numero specificato di byte, iniziando dalla sua 
posizione corrente (Position), caricandoli in un buffer. La lettura quindi sposta la 
posizione corrente del numero di byte effettivamente trasferiti. II prototipo per Read e 

virtual int __fastcall Read(void *Buffer, int Count); 

Read e utile quando il numero di byte del file non e noto. Read restituisce il numero di 
byte effettivamente trasferiti, che puo essere minore di Count se lo stream non 
conteneva Count byte di dati precedenti alia posizione corrente. 

Write e una funzione che scrive Count byte dal buffer nel file associato alio stream, 
partendo dalla Position corrente. II prototipo per Write e: 

virtual int fastcall Write(const void *Buffer, int Count); 

Dopo la scrittura nel file, Write sposta la posizione corrente del numero di byte scritti, 
e restituisce il numero di byte effettivamente scritti, che puo essere minore di Count 
se incontra la fine del buffer oppure se lo stream non puo accettare piu byte. 

Le procedure complementari sono ReadBuffer e WriteBuffer che, a differenza di Read e 
Write, non restituiscono il numero di byte letti o scritti. Queste procedure sono utili 
nei casi in cui il numero di byte e noto e sono necessarie, per esempio, per la lettura 
delle strutture. ReadBuffer e WriteBuffer generano un'eccezione (EReadError e 
EWriteError) se il Count byte non corrisponde esattamente. Cio e in contrasto con i 
metodi Read e Write, che possono restituire un numero di byte diverso dal valore 
chiesto. I prototipi per ReadBuffer e WriteBuffer sono: 

virtual int __fastcall ReadBuffer (void *Buffer, int Count); 

virtual int __fastcall WriteBuffer (const void *Buffer, int Count); 

Questi metodi chiamano i metodi Read e Write, per eseguire una lettura e una 
scrittura effettive. 
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Lettura e scrittura di componenti 

T Stream definisce metodi specializzati, ReadComponent e WriteComponent, per la 
lettura e la scrittura di componenti. E possibile utilizzarli nelle applicazioni come un 
modo per salvare i componenti e le rispettive proprieta quando li si crea o li si 
modifica in fase di esecuzione. 

ReadComponent e WriteComponent sono i metodi che TIDE utilizza per leggere o 
scrivere i componenti nei file scheda. Durante la lettura o la scrittura da o in un file 
scheda, le classi stream operano con le classi TFiler, TReader e TWriter, per leggere 
oggetti dal file scheda o per scriverli su disco. Per ulteriori informazioni sull'uso del 
sistema di streaming dei componenti, consultare nella guida di riferimento in linea le 
classi TStream, TFiler, TReader, TWriter, e TComponent. 

Copia di dati da uno stream a un altro 



Quando si copiano dati da uno stream a un altro, non e necessario leggere 
esplicitamente e poi scrivere i dati. E possibile invece utilizzare il metodo CopyFrom, 
come illustrate nell'esempio seguente. 

L'applicazione include due controlli di testo (From e To) e un pulsante Copy File. 

void __fastcall TForml: :CopyFileClick(TObject *Sender) 

{ 

TStream* streaml= new TFileStream(Frora->Text, fmOpenRead I fmShareDenyWrite) ; 
try 

{ 

TStream* stream2 = new TFileStream(To->Text, fmOpenWrite I fmShareDenyRead) ; 
try 

{ 

stream2 -> CopyFrom (streaml, streaml->Size) ; 

} 

finally 

{ 

delete stream2; 

} 

} 

finally 

{ 

delete streaml; 

} 

} 

Specifica della posizione e della dimensione dello stream 



Oltre ai metodi per leggere e scrivere, questi oggetti consentono alle applicazioni di 
posizionarsi ad una posizione arbitraria nello stream oppure di cambiarne le 
dimensioni . Una volta individuata la posizione specificata, la successiva operazione 
di lettura o di scrittura inizia la lettura da o la scrittura nello stream a partire da 
quella posizione. 
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Ricerca di una posizione specifica 

II metodo Seek e il meccanismo piu generale per spostarsi a una particolare posizione 
nello stream. Esistono due ridefinizioni per il metodo Seek: 

virtual int fastcall Seekfint Offset, Word Origin); 

virtual __int64 __fastcall Seek(const __int64 Offset, TSeekOrigin Origin); 

Entrambe le definizoni funzionano alio stesso modo. La differenza e che una versione 
utilizza un intero a 32 bit per rappresentare le posizioni e gli offset, mentre l'altro 
utilizza un intero a 64 bit. 

II parametro Origin indica come interpretare il parametro Offset. Origin sara uno dei 
seguenti valori: 

Valore Significato 

soFromBeginning Offset e dall'inizio della risorsa. Seek sposta alia posizione Offset. Offset deve 
essere >= 0. 

soFromCurrent Offset e dalla posizione corrente nella risorsa. Seek sposta alia Position E 
Offset. 

soFromEnd Offset e dalla fine della risorsa. Offset deve essere <= per indicare un 

numero di byte prima della fine del file. 

Seek azzera la Position corrente dello stream, spostandola dello scostamento indicate 
Seek restituisce la nuova posizione corrente nello stream. 

Utilizzo delle proprieta Position e Size 

Tutti gli stream hanno una serie di proprieta che contengono la posizione e le 
dimensioni correnti. Queste proprieta sono utilizzate dal metodo Seek, oltre che da 
tutti i metodi che leggono dallo o scrivono nello stream. 

La proprieta Position indica l'offset corrente, in byte, nello stream (a partire dall'inizio 
dello stream di dati). 

La proprieta Size indica le dimensioni in byte dello stream. Puo essere utilizzata per 
determinare il numero di byte disponibili per la lettura o per troncare i dati nello 
stream. 

Size viene usata internamente dalle routine che leggono e scrivono nello stream. 

L'impostazione della proprieta Size cambia le dimensioni dei dati nello stream. Ad 
esempio,in un file stream, viene usata come marcatore di fine file per troncare il file. 
Se le dimensioni Size del stream non possono essere cambiate, viene sollevata 
un'eccezione. Ad esempio, il tentativo di cambiare Size di uno stream di file di sola 
lettura solleva un'eccezione. 

Operazioni con i file 



BaseCLX supporta diversi modi per operare con i file. Oltre all'utilizzo degli stream 
di file, ci sono numerose routine di libreria di esecuzione per operazioni di I/O si file. 
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Sia gli stream di file che le routine globali per leggere da e scrivere su file sono 
descritti in "Approccio alle operazioni di I/O su file" on page 4-5. 

Oltre alle operazioni di input /output, si potrebbero volere trattare i file su disco. II 
supporto per le operazioni sui file invece che sul loro contenuto e descritto in 
"Manipolazione dei file" a pagina 4-7. 

Durante l'utilizzo della CLX in applicazioni cross-platform, e bene ricordare che 
benche il linguaggio Object Pascal non sia sensibile alle differenze fra maiuscole e 
minuscole, lo e invece il sistema operativo Linux. Utilizzando gli oggetti e le routine 
che operano con i file, bisogna prestare attenzione a come sono scritti i nomi dei file. 

Approccio alle operazioni di I/O su file 



Ci sono tre modalita per affrontare le operazioni di lettura e di scrittura su file: 

• II metodo consigliato per operare con i file e l'utilizzo degli stream di file. Gli 
stream di file sono istanze oggetto della classe TFileStream utilizzata per accedere 
alle informazioni in file su disco. Gli stream di file sono un approccio portatile e di 
alto livello alle operazoni di I/O su file. Poiche gli stream di file rendono 
disponibile l'handle del file, questo approccio puo essere combinato con quello 
successivo. La sezione successiva, "Uso degli stream di file" tratta in dettaglio 
TFileStream. 

• E possibile operare con file utilizzando un approccio basato su handle. Gli handle 
di file sono forniti dal sistema operativo quando si crea un file o lo si apre per 
operare con il suo contenuto. La unit SysUtils definisce molte routine di gestione 
file che operano con file utilizzando un handle di file. In Windows, di solito, 
queste routine sono wrapper per funzioni API di Windows. Poiche le funzioni 
Delphi usano la sintassi Object Pascal e occasionalmente forniscono valori di 
parametri predefiniti, esse costituiscono una comoda interfaccia per le API di 
Windows. Inoltre, esistono le versioni corrispondenti in Linux, cosicche e possibile 
utilizzare queste routine in applicazioni multipiattaforma. Per utilizzare un 
approccio basato su handle, per prima cosa si deve aprire apre un file utilizzando 
la funzione FileOpen o creare un nuovo file utilizzando la funzione FileCreate. Una 
volta ottenuto l'handle, utilizzare routine basate su handle per operare con il 
contenuto (scrittura di una riga, lettura del testo, e cosi via). 

• La libreria di esecuzione del C e la libreria standard C++ includono molte funzioni 
e classi per le attivita con file. Queste hanno il vantaggio che possono essere 
utilizzate in applicazioni che non utilizzano la VCL o le CLX. Per informazioni su 
queste funzioni, vedere la documentazione online per la libreria di esecuzione del 
C o per la libreria standard C++. 

Uso degli stream di file 



TFileStream e una classe che consente alle applicazioni di effettuare operazioni di 
lettura e scrittura sui file su disco. E usata per le rappresentazioni ad alto livello degli 
oggetti degli stream di file. Poiche TFileStream e un oggetto stream, condivide i 
metodi dei comuni stream. E possibile utilizzare questi metodi per leggere da o per 
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scrivere su un file, per copiare i dati da altre classi stream o in altre classi, e leggere o 
scrivere i valori dei componenti. Vedere "Uso di stream" a pagina 4-2 per i dettagli 
sulle capacita che gli stream di file ereditano essendo classi stream. 

Inoltre, gli stream di file danno accesso alio handle dei file, rendendo cosi possibile il 
loro utilizzo con routine globali di gestione dei file che richiedono l'handle di file. 

Creazione e aperture di file con stream di file 

Per creare o aprire un file e avere accesso ad un handle per il file, basta istanziare un 
TFileStream. Questa operazione apre un determinato file e fornisce i metodi per la 
lettura o la scrittura relative. Se il file non puo essere aperto, TFileStream solleva 
un'eccezione. 

fastcall TFileStream (const AnsiString FileName, Word Mode) ; 

II parametro Mode specifica come verra aperto il file quando si crea lo stream di file. II 
parametro Mode e costituito da una modalita open e da una modalita share OR+ed 
contemporaneamente. La modalita open puo assumere uno dei seguenti valori: 

Tabella 4.1 Modalita Open 
Valore Significato 

fmCreate Inserisce in TFileStream un file con un determinato nome. Se esiste un file 

con quel dato nome, apre il file in modo scrittura. 

fmOpenRead Apre il file per la sola lettura. 

fmOpen Write Apre il file per la sola scrittura. La scrittura nel file sostituisce 

completamente il contenuto attivo. 

fmOpenReadWrite Apre il file per modificare il contenuto attivo anziche sostituirlo. 

La modalita share puo assumere uno dei seguenti valori con le limitazioni elencate di 
seguito: 

Tabella 4.2 Modalita Share 
Valore Significato 

fmShareCompat La condivisione e compatibile con il modo in cui vengono aperti gli FCB. 

fmShareExclusive Le altre applicazioni non possono aprire il file per nessun motivo. 

fmShareDenyWrite Le altre applicazioni possono aprire il file per la lettura, ma non per la 
scrittura. 

fmShareDenyRead Le altre applicazioni possono aprire il file per la scrittura, ma non per la 
lettura. 

fmShareDenyNone Non viene fatto alcun tentativo per impedire alle applicazioni di leggere 
da o scrivere nel file. 
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Si noti che la modalita share che e possibile utilizzare dipende dalla modalita open 
che e stata utilizzata. La seguente tabella mostra le modalita share disponibili per 
ogni modalita open. 

Tabella 4.3 Modalita shared disponibili per ogni modalita open 

Open Mode fmShareCompat fmShareExclusive fmShareDenyWrite fmShareDenyRead fmShareDenyNone 

fmOpenRead Non utilizzabile Non utilizzabile Disponibile Non utilizzabile Disponibile 

fmOpenWrite Disponibile Disponibile Non utilizzabile Disponibile Disponibile 

fmOpenReadWrite Disponibile Disponibile Disponibile Disponibile Disponibile 

Le costanti delle modalita open e share sono definite nella unit SysUtils. 

Uso dell'handle di file 

Quando si istanzia TFileStream, si ottiene l'accesso all'handle dei file. Questo file e 
contenuto nella proprieta Handle. In Windows, Handle e un handle di file Windows. 
Nelle versioni Linux della CLX, e un handle di file Linux. Handle e una proprieta a 
sola lettura che indica il modo in cui il file viene aperto. Se si vogliono cambiare gli 
attributi dell'handle di file, occorre creare un nuovo oggetto flusso di file. 

Alcune routine per la manipolazione dei file accettano un handle di file come 
parametro. Quando si ha uno stream di file, e possibile usare la proprieta Handle in 
qualsiasi situazione in cui si pud usare un handle di file. Bisogna prestare attenzione 
al fatto che, a differenza dei flussi di handle, i flussi di file chiudono gli handle dei file 
quando l'oggetto viene distrutto. 



Manipolazione dei file 



Nella libreria runtime di the BaseCLX sono incorporate molte delle comuni 
operazioni sui file. Le procedure e le funzioni per lavorare con i file operano ad alto 
livello. Per la maggior parte delle routine, bisogna specificare il nome del file e la 
routine che effettua automaticamente le chiamate necessarie al sistema operativo. In 
alcuni casi, si utilizzano invece handle di file. 

Benche il linguaggio Object Pascal non sia sensibile alle differenze fra maiuscole e 
minuscole, lo e invece il sistema operativo Linux. Prestare molta attenzione all'uso di 
maiuscole /minuscole quando si lavora con file in applicazioni multipiattaforma. 



Cancellazione di un file 

La cancellazione elimina il file dal disco e ne rimuove la voce dalla relativa directory. 
Non esiste una operazione corrispondente che permetta di ripristinare un file 
cancellato; generalmente, quindi, le applicazioni chiederanno agli utenti di 
confermare la cancellazione dei file. Per cancellare un file, basta passare il suo nome 
alia funzione DeleteFile: 

DeleteFile(FileName) ; 
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DeleteFile restituisce true se il file viene cancellato, false in caso contrario (per 
esempio, se il file non esiste oseea sola lettura). DeleteFile elimina il file chiamato da 
FileName dal disco. 

Ricerca di un file 

Per trovare un file si usano tre routine: FindFirst, FindNext, and FindClose. FindFirst 
cerca la prima istanza del nome di un file con un certo set di attributi in una 
determinata directory. FindNext restituisce il primo file corrispondente al nome e agli 
attributi specificati in una precedente chiamata a FindFirst. FindClose rilascia la 
memoria allocata da FindFirst. Si deve usare sempre FindClose per concludere una 
sequenza FindFirst /FindNext. Per sapere se un file esiste, c'e una funzione FileExists 
che restituisce true in caso affermativo, false in caso contrario. 

Le tre routine di ricerca dei file accettano TSearchRec come parametro. TSearchRec 
definisce le informazioni sul file cercate da FindFirst o FindNext. La dichiarazione per 

TSearchRec e: 

struct TSearchRec 

{ 

int Time; // time stamp of the file 

int Size; // size of the file in bytes 

int Attr; // file attribute flags 

AnsiString Name; // filename and extension 

int ExcludeAttr; // file attribute flags for files to ignore 

unsigned FindHandle; 

_WIN32_FIND_DATAA FmdData; // structure with addition information 

} ; 

Se viene trovato un file, i campi del parametro di tipo TSearchRec vengono modificati 
per descrivere il file trovato. E possibile verificare Attr con le seguenti costanti o 
valori per determinare se un file ha uno specifico attributo: 



Tabella 4.4 Costanti di attributo e valori 



Costante 


Valore 


Descrizione 


faReadOnly 


0x00000001 


File a sola lettura 


faHidden 


0x00000002 


File nascosti 


faSysFile 


0x00000004 


File di sistema 


faVolumelD 


0x00000008 


File ID volume 


faDirectory 


0x00000010 


File di directory 


faArchive 


0x00000020 


File archivio 


faAnyFile 


0x0000003F 


File di qualsiasi tipo 



Per verificare un attributo, bisogna abbinare il valore del campo Attr alia costante di 
attributo con l'operatore &. Se il file ha quell'attributo, il risultato sara maggiore di 0. 
Ad esempio, se il file trovato e un file nascosto, la seguente espressione sara valutata 
come true: {S ear chRec. Attr and faHidden> 0). Gli attributi possono essere combinati 
eseguendo l'OR delle rispettive costanti o dei valori. Ad esempio, per cercare i file 
nascosti e a sola lettura oltre ai normali file, si puo passare l'attributo 
(faReadOnlyoppure/flHfdden) al parametro Attr. 



4-8 Guida alia programmazione 



Operazioni con i file 



Questo esempio usa un'etichetta, un pulsante di nome Search e un pulsante di nome 
Again su una scheda. Quando l'utente fa clic sul pulsante Search, viene trovato il 
primo file nel percorso specificato, e il nome e il numero di byte del file appaiono nel 
titolo dell'etichetta.Ogni volta che l'utente fa clic sul pulsante Again, nell'etichetta 
vengono visualizzati le dimensioni e il nome corrispondenti del file: 

TSearchRec SearchRec; // global variable 

void __fastcall TForml: :SearchClick(TObject *Sender) 

{ 

FindFirst ("c: WProgram Files\\bcb6\\bin\\* . *" , faAnyFile, SearchRec); 

Labell->Caption = SearchRec ->Name + " is " + IntToStr(SearchRec.Size) + " bytes in size"; 

} 

void __fastcall TForml: : AgainClick (TObject *Sender) 

{ 

if (FindNext (SearchRec) == 0) 
Labell->Caption = SearchRec->Name + " is " + IntToStr (SearchRec. Size) + " bytes in 
size" ; 
else 

FindClose(SearchRec) ; 

} 

Nelle applicazioni multipiattaforma, tutti i nomi di percorso scritti direttamente nel 
codice vanno sostituiti con il percorso corretto per il sistema, oppure si devono 
utilizzare variabili di ambiente per rappresentare tali percorsi (sulla pagina 
Environment Variables selezionare il comando Tools I Environment Options. 

Cambiamento del nome di un file 

Per modificare un nome file, utilizzare la f unzione RenameFile: 

extern PACKAGE bool __fastcall RenameFile (const AnsiString OldName, const AnsiString 
NewName ) ; 

RenameFile cambia il nome, identificato da OldFileName, con il nome specificato da 
NewFileName. Se l'operazione ha successo, RenameFile restituisce true. Se non e 
possibile rinominare il file, (ad esempio, se un file chiamato NewFileName esiste gia), 
RenameFile restituisce false. Ad esempio: 

if ( IRenameFile ("OLDNAME. TXT" , "NEWAME.TXT") ) 
ErrorMsg ( "Error renaming file!"); 

E impossibile rinominare (spostare) un file nelle unita usando RenameFile. Prima 
bisogna copiare il file e poi cancellare il vecchio. 

RenameFile nella libreria runtime BaseCLX e un wrapper per la funzione MoveFile 
delle API di Windows, e pertanto nemmeno MoveFile funzionera sulle varie unita. 

Routine per data-ora 

Le routine FileAge, FileGetDate e FileSetDate operano sui valori data-ora del sistema 
operative FileAge restituisce la data e l'ora di registrazione di un file, o -1 se il file non 
esiste. FileSetDate imposta la data e l'ora di registrazione per un determinato file, e 
restituisce zero se l'esito e positivo, o un codice di errore se l'esito e negative 
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FileGetDate restituisce la data e l'ora di registrazione per il file specificato o -1 se 
l'handle non e corretto. 

Analogamente a molte altre routine per il trattamento dei file, FileAge utilizza un 
nome di file di tipo string. FileGetDate e FileSetDate, tuttavia, utilizzano un parametro 
integer che accetta un handle di file. Per ottenere l'handle di file e possibile 

• Utilizzare la funzione FileOpen o FileCreate per creare un nuovo file o aprire un file 
esistente. Sia FileOpen che FileCreate restituiscono un handle di file. 

• Istanziare TFileStream per creare o aprire un file. Quindi utilizzarne la proprieta 
Handle. Per ulteriori informazioni, vedere "Uso degli stream di file" a pagina 4-5. 

Copia di un file 

La libreria runtime non fornisce tutte le routine per copiare un file. Comunque, se si 
stanno scrivendo applicazioni per l'ambiente Windows, per chiamare un file, e 
possibile chiamare direttamente la funzione API CopyFile di Windows. Come la 
maggior parte delle routine della libreria runtime , CopyFile accetta un nome di file 
come parametro, e non un handle di file. Quando si copia un file, occorre fare 
attenzione che nel nuovo file vengano copiati gli attributi del file esistente, ma non 
quelli relativi alia sicurezza. CopyFile e utile anche nello spostamento dei file nelle 
unita, perche ne la funzione RenameFile ne la funzione API MoveFile possono 
rinominare oppure spostare i file nelle unita. Per ulteriori informazioni, consultare la 
Guida in linea di Microsoft Windows. 

Operazioni con file ini e con il Registro di sistema 



Molte applicazioni utilizzano i file ini per memorizzare le informazioni di 
configurazione. BaseCLX include due classi per le operazioni con i file ini: TIniFile e 
TMemlniFile. L'utilizzo dei file ini ha il vantaggio che possono essere utilizzati in 
applicazioni multipiattaforma e sono semplici da leggere e da modificare. Per 
informazioni su queste classi, vedere "Utilizzo di TIniFile e di TMemlniFile" a 
pagina 4-11 per ulteriori informazioni. 

Molte applicazioni Windows sostituiscono l'utilizzo di file ini con il Registro di 
sistema. II file di registro di sistema di Windows e un database gerarchico che agisce 
come uno spazio di memoria centralizzato per informazioni di configurazione . La 
VCL include classi per operare con il Registro di sistema. Benche dal punto di vista 
tecnico non facciano parte di BaseCLX (poiche essi sono disponibili solo in 
Windows), due di queste classi, TRegistrylniFile e TRegistry, sono trattati in questa 
sezione grazie alia loro somiglianza con le classi usate per operare con i file ini. 

TRegistrylniFile e utile per applicazioni multipiattaforma, poiche condivide un 
antenato comune (TCustomlniFile) con le classi che operano con file ini. Se ci si limita 
ad utilizzare i metodi dell'antenato comune (TCustomlniFile) l'applicazione puo 
funzionare su entrambe le applicazioni con pochissimo codice condizionale. 
TRegistrylniFile e trattato in "Utilizzo di TRegistrylniFile" a pagina 4-12. 

Nel caso di applicazioni che non sono multipiattaforma, e possibile utilizzare la 
classe TRegistry. Le proprieta e i metodi di TRegistry hanno nomi che corrispondono 
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piu direttamente al modo in cui e organizzato il Registro di sistema, in quanta non e 
necessario che siano compatibili con le classi per i file ini. TRegistry e trattato in "Uso 
di TRegistry" a pagina 4-12. 

Utilizzo di TlniFile e di TMemlniFile 

II formato dei file ini e ancora molto diffuso, e molti file di configurazione (come il 
file DSK delle impostazioni del Desktop) sono in questo formato. Questo formato e 
particolarmente utile in applicazioni multipiattaforma, in cui e impossibile fare 
af fidamento su un Registro di sistema per la memorizzazione delle informazioni di 
configurazione. BaseCLX fornisce due classi, TlniFile e TMemlniFile, per semplificare 
le operazioni di lettura e di scrittura con i file ini. 

In Linux, TMemlniFile e TlniFile sono identiche. Su Windows, TlniFile opera 
direttamente sul file ini su disco mentre TMemlniFile registra tutte le modifiche in 
memoria e non le scrive sul disco finche non si chiama il metodo UpdateFile. 

Quando si crea un'istanza dell'oggetto TlniFile oppure TMemlniFile , si passa al 
costruttore il nome del file INI come parametro. Se il file non esiste, viene creato 
automaticamente. Sara quindi possibile leggere i valori utilizzando metodi di lettura 
come ReadString,ReadDate Readlnteger o ReadBool. In alternativa, se si desidera leggere 
un'intera sezione del file ini, e possibile utilizzare il metodo ReadSection. 
Analogamente, e possibile scrivere valori utilizzando metodi come WriteBool, 
Writebiteger, o WriteString. 

Di seguito e riportato un esempio di lettura da un file ini delle informazioni di 
configurazione nel costruttore di una scheda e di scrittura dei valori nel gestore di 
evento OnClose. 

__fastcall TForml: :TForml (TComponent *0wner) : TForm(Owner) 
{ 

TlniFile *ini; 

ini = new TlniFile) ChangeFileExt ( Application->ExeName, ".INI" ) ); 

Top = ini->ReadInteger ( "Form", "Top", 100 ) ; 
Left = ini->ReadInteger ( "Form", "Left", 100 ) ; 
Caption = ini->ReadString( "Form", "Caption", 

"Default Caption" ) ; 
ini->ReadBool ( "Form", "InitMax", false ) ? 

WindowState = wsMaximized : 

WindowState = wsNormal; 

delete ini; 



void fastcall TForml: :FormClose(TObject *Sender, TCloseAction &Action) 

{ 

TlniFile *ini; 

ini = new TlniFile (ChangeFileExt ( Application->ExeName, ".INI" ) ) ; 
ini->WriteInteger ( "Form", "Top", Top ) ; 
ini->WriteInteger ( "Form", "Left", Left ) ; 
ini->WriteString ( "Form", "Caption", Caption ) ; 
ini->WriteBool ( "Form", "InitMax", 

WindowState == wsMaximized ) ; 
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delete ini; 

} 

Ognuna delle routine Read accetta tre parametri. II primo parametro identifica la 
sezione del file ini. II secondo parametro identifica il valore che si desidera leggere e 
il terzo e un valore predefinito nel caso la sezione o il valore non esista nel file ini. 
Esattamente come i metodi Read gestiscono le situazioni in cui una sezione o un 
valore non esistono, le routine Write creano la sezione e/o il valore nel caso esse non 
esistano. La prima volta che viene eseguito, il codice di esempio crea un file INI 
simile al seguente: 

[Form] 

Top=185 

Left=280 

Caption=Default Caption 
InitMax=0 

Alle successive esecuzioni dell'applicazione, i valori del file ini saranno letti al 
momento della creazione della scheda, e riscritti nel file nell'evento OnClose. 

Utilizzo di TRegistrylniFile 

La maggior parte delle applicazioni a 32-bit memorizzano le proprie informazioni nel 
file di registro invece che nel file ini poiche il file di registro e gerarchico e non e 
soggetto ai limiti sulle dimensione dei file ini. Se si e abituati ad utilizzare i file ini e si 
vogliono spostare invece le informazioni di configurazione nel file di registro, e 
possibile utilizzare la classe TRegistrylniFile. Si potrebbe anche volere utilizzare 
TRegistrylniFile in applicazioni multipiattaforma nel caso si voglia utilizzare il 
Registro di sistema in Windows e un file ini in Linux. E possibile scrivere la maggior 
parte dell'applicazione in modo che utilizzi il tipo TCustomlniFile. E necessario solo 
condizionare il codice che crea un'istanza di TRegistrylniFile (in Windows) o 
TMemlniFile (in Linux) e assegnarla al TCustomlniFile utilizzato dall'applicazione. 

TRegistrylniFile e progettata per far si che le voci del file di registro assomiglino alle 
voci del file INI. Tutti i metodi di TIniFile e di TMemlniFile (lettura e scrittura) 
esistono in TRegistrylniFile. 

Quando si costruisce un oggetto TRegistrylniFile , il parametro che si passa (il nome 
file per un oggetto IniFile oppure un oggetto TmemlniFile) diventa un valore di 
chiave nelle chiavi utente nel file di registro e tutte le sezioni e i valori dipendono da 
quella radice. Tutte le sezioni e i valori sono ramificazioni di quella radice. 
TRegistrylniFile semplifica notevolmente l'interfaccia del file di registro, tanto che lo 
si utilizzera al posto del componente di TRegistry, anche se non si sta convertendo del 
codice esistente o scrivendo un'applicazione cross-platform. 

Uso di TRegistry 

Se si sta scrivendo un'applicazione solamente per Windows e la struttura del 
Registro di sistema e familiare, e possibile utilizzare TRegistry. A differenza di 
TRegistrylniFile, che utilizza le stesse proprieta e metodi degli altri componenti per 
file ini, le proprieta e i metodi di TRegistry corrispondono piu direttamente alia 
struttura del Registro di sistema. Ad esempio, TRegistry permette di specificare sia la 
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chiave radice che la sottochiave, mentre TRegistry assume HKEY_CURRENT_USER 
come chiave radice. Oltre ai metodi per aprire, chiudere, salvare, spostare, copiare e 
cancellare chiavi, TRegistry permette di specificare il livello di accesso che si desidera 
utilizzare. 

TRegistry non e utilizzabile per programmi multipiattaforma. 
L'esempio seguente recupera un valore da una voce del file di registro: 

♦include <Registry .hpp> 

AnsiString GetRegistryValue (AnsiString KeyName) 

{ 

AnsiString S; 

TRegistry *Registry = new TRegistry (KEY_READ) ; 
try 

{ 

Registry->RootKey = HKEY_LOCAL_MACHINE ; 

// False because we do not want to create it if it doesn't exist 
Regi s t ry - >0p enKey ( KeyName .false); 
S = Registry->ReadString("VALUEl") ; 

} 

__finally 

{ 

delete Registry; 

} 

return S; 

} 



Operazioni con le liste 



BaseCLX include molte classi che rappresentano elenchi o raccolte di elementi. Esse 
variano a seconda dei tipi di elementi che contengono, delle operazioni che 
supportano e dal fatto che siano o meno persistenti. 

La seguente tabella elenca diverse classi di elenco e indica i tipi di elementi che 
contengono: 

Tabella 4.5 Classi per la gestione di elenchi 



Oggetto 


Significato 


TList 


Elenco di puntatori 


TThreadList 


Un elenco thread-safe di puntatori 


TBucketList 


Un elenco hashed di puntatori 


TObjectBucketList 


Un elenco hashed di istanze di oggetti 


TObjectList 


Elenco di istanze di oggetti gestito in memoria 


TComponentList 


Elenco di componenti gestito in memoria (ovvero, istanze di classi 




derivate da TComponent) 


TClassList 


Un elenco di riferimenti di classe (metaclassi) 


TInterfaceList 


Un elenco di puntatori a interfacce. 


TQueue 


Elenco di puntatori FIFO (first-in, first-out) 
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Tabella 4.5 Classi per la gestione di elenchi 



Oggetto 

T Stack 

TObjectQueue 

TObjectStack 

TCollection 

TStringList 

THashedStringList 



Significato 

Elenco di puntatori LIFO (last-in, first-out) 
Elenco di oggetti FIFO (first-in, first-out) 
Elenco di oggetti LIFO (last-in, first-out) 

Classe base per molte classi specializzate di elementi con tipo. 
Elenco di stringhe 

Un elenco di stringhe con nel formato Name=Value, hashed per 
prestazioni. 



Operazioni comuni su elenchi 



Benche le diverse classi di elenco contengano vari tipi di elementi e abbiano vari 
progenitori, la maggior parte di loro condivide un insieme comune di metodi per 
aggiungere, cancellare, riordinare e accedere agli elementi nell'elenco. 

Aggiunta di elementi di un elenco 

La maggior parte delle classi di elenco hanno un metodo Add, che permette di 
aggiungere un elemento alia fine dell'elenco (se non e ordinato) o nella posizione 
appropriata (se l'elenco e ordinato). Di soli to, il metodo Add accetta come parametro 
l'elemento che si aggiunge all'elenco e restituisce la posizione nell'elenco in cui e 
stato aggiunto l'elemento. Nel caso di bucket lists (TBucketList e TObjectBucketList), 
Add accetta non solo l'elemento da aggiungere, ma anche un dato che e possibile 
associare a quell'elemento. Nel caso di collection, Add non accetta alcun parametro, 
ma crea un nuovo elemento che aggiunge. II metodo Add sulle collection restituisce 
l'elemento che ha aggiunto, in modo che sia possibile assegnare valori alle proprieta 
del nuovo elemento. 

Oltre al metodo Add, alcune classi di elenco hanno un metodo Insert. Insert funziona 
esattamente come il il metodo Add, ma ha un parametro aggiuntivo che consente di 
specificare la posizione nell'elenco in cui si desidera che venga visualizzato il nuovo 
elemento. Se una classe ha un metodo Add, ha anche un metodo Insert a meno che la 
posizione degli elementi non sia predeterminata. Ad esempio, e impossibile 
utilizzare Insert con elenchi ordinati poiche gli elementi devono essere messi secondo 
la sequenza di ordinamento ed e impossibile utilizzare Insert con bucket lists poiche 
l'algoritmo hash determina la posizione dell'elemento. 

Le uniche classi che non hanno un metodo Add sono gli elenchi ordinati. Gli elenchi 
ordinati sono code e stack. Per aggiungere elementi a un elenco ordinato, utilizzare 
invece il metodo Push. Push, come Add, accetta un elemento come parametro e lo 
inserisce nella posizione corretta. 

Cancellazione degli elementi di un elenco 

Per cancellare un singolo elemento da una delle classi di elenco, utilizzare il metodo 
Delete oppure il metodo Remove. Delete accetta un solo parametro, il nome 
dell'elemento da rimuovere. Anche Remove accetta un singolo parametro ma quel 
parametro e un riferimento all'elemento da rimuovere, invece del suo indice. Alcune 
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classi di elenco supportano solo un metodo Delete, alcune supportano solo un metodo 
Remove e alcune li hanno entrambi. 

Come con l'aggiunta di elementi, gli elenchi ordinati si comportano diversamente di 
tutti gli altri elenchi. Invece di utilizzare un metodo Delete o Remove, si rimuove un 
elemento da un elenco ordinato chiamando il metodo Pop. Pop non accetta alcun 
argomento, in quanto c'e solo un elemento che puo essere rimosso. 

Se si vogliono cancellare tutti gli elementi nell'elenco, e possibile chiamare il metodo 
Clear. La cancellazione e disponibile per tutti gli elenchi tranne quelli ordinati. 

Accesso agli elementi di un elenco 

Tutte le classi di elenco (tranne TThreadList e gli elenchi ordinati) hanno una 
proprieta che permette di accedere agli elementi nell'elenco. Di solito, questa 
proprieta e chiamata Items. Per gli elenchi di stringhe, la proprieta e chiamata Strings 
e per elenchi bucket e chiamata Data. Le proprieta Items, Strings o Data sono proprieta 
indicizzate e pertanto e possibile specificare a quale elemento si desidera accedere. 

Su TThreadList, e necessario bloccare l'elenco prima di potere accedere agli elementi. 
Quando si blocca l'elenco, il metodo LockList restituisce un oggetto TList che e 
possibile utilizzare per accedere agli elementi. 

Solo gli elenchi ordinati permettono di accedere all'elemento "superiore" dell'elenco. 
E possibile ottenere un riferimento a questo elemento chiamando il metodo Peek. 

Riordinamento degli elementi di un elenco 

Alcune classi di elenco hanno metodi che permettono di riordinare gli elementi 
nell'elenco. Alcune hanno un metodo Exchange, che scambia la posizione di due 
elementi. Alcune hanno un metodo Move che permette di spostare un elemento in 
una posizione specificata. Alcune hanno un metodo Sort che permette di ordinare gli 
elementi nell'elenco. 

Per vedere quali metodi sono disponibili, controllare la Guida in linea relativamente 
alia classe di elenco che si sta utilizzando. 

Elenchi persistenti 



Gli elenchi persistenti possono essere salvati in un file scheda. Per questo motivo, 
sono speeso utilizzati come tipi di una proprieta pubblicata di un componente. E 
possibile aggiungere elementi all'elenco in fase di progettazione e quegli elementi 
vengono salvati con l'oggetto in modo che essi siano presenti quando il componente 
che li utilizza viene caricato in memoria in fase esecuzione. Ci sono due tipi principali 
di elenchi persistenti: elenchi di stringhe e collection. 

Come esempi di elenchi di stringhe si possono citare TStringList e THashedStringList. 
Gli elenchi di stringhe, come dice anche il nome, contengono stringhe. Essi 
forniscono un supporto speciale per stringhe in formato Name= Value, in modo che 
sia possibile reperire il valore associato a un nome. Inoltre, la maggior parte degli 
elenchi di stringhe permettono di associare un oggetto a ogni stringa nell'elenco. Le 
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liste di stringhe sono descritte in modo piu dettagliato in "Operazioni con elenchi di 
stringhe" a pagina 4-16. 

Le collection discendono dalla classe TCollection. Ogni discendente TCollection e 
specializzato nella gestione di una specifica classe di elementi, dove quella classe 
discende da TCollectionltem. Le collection supportano la maggior parte delle comuni 
operazioni sugli elenchi. Tutte le collection sono progettate per essere del tipo di una 
proprieta pubblicata, e molte non possono funzionare in modo indipendente 
dall'oggetto che le utilizza per implementare una delle sue proprieta. In 
progettazione, la proprieta il cui valore e una raccolta pud utilizzare il Collection 
editor l'editor per consentire l'aggiunt , la rimozione e il riordino di elementi. II 
Collection editor fornisce un'interfaccia utente comune per il trattamento delle 
collection 

Operazioni con elenchi di stringhe 



Uno dei tipi di elenco piu comunemente utilizzato e un elenco di stringhe di caratteri. 
Alcuni esempi potrebbero essere gli elementi di una casella combinata, le righe di un 
memo, i nomi dei tipi di carattere o i nomi di righe e colonne in una griglia per 
stringhe. La VCL mette a disposizione un'interfaccia comune per un qualsiasi elenco 
di stringhe mediante un oggetto di nome TStrings e mediante derivati come 
TStringList e THashedStringlist. TStringList implementa le proprieta e i metodi 
astratti introdotti da TStrings e introduce proprieta, eventi e metodi per 

• Ordinare le stringhe nell'elenco. 

• Evitare stringhe duplicate negli elenchi ordinati. 

• Rispondere alle modifiche apportate ai contenuti dell'elenco. 

Oltre alle funzionalita per gestire gli elenchi di stringhe, questi oggetti consentono 
un'interazione oltremodo semplice; ad esempio, e possibile modificare le righe di un 
memo, (che e un'istanza di TStrings) e quindi utilizzare queste righe come elementi 
di una casella combinata (che e anch'essa un'istanza di TStrings). 

Con gli oggetti TStrings nella colonna Value dell'Object Inspector e disponibile una 
proprieta per gestire gli elenchi di stringhe. Fare doppio clic su TStrings per aprire lo 
String List editor, in cui e possibile modificare, aggiungere o cancellare righe. 

Con gli oggetti string-list e possibile operare anche in fase di esecuzione per eseguire 
operazioni quali 

• Caricamento e salvataggio di elenchi di stringhe 

• Creazione di un nuovo elenco di stringhe 

• Gestione di stringhe in un elenco 

• Associazione di oggetti ad un elenco di stringhe 

Caricamento e salvataggio di elenchi di stringhe 



Gli oggetti string-list mettono a disposizione metodi SaveToFile e LoadFromFile che 
consentono di memorizzare un elenco di stringhe in un file di testo e caricano un file 
di testo in un elenco di stringhe. Ciascuna riga del file di testo corrisponde a una 



4-16 Guida alia programmazione 



Operazioni con elenchi di stringhe 

stringa dell'elenco. Utilizzando questi metodi, e possibile, per esempio, creare un 
semplice editor di testi caricando un file in un componente memo, oppure salvare 
liste di elementi per caselle combinate. 

L'esempio seguente carica una copia del file WIN.INI in un campo memo ed esegue 
una copia di riserva di nome WIN.BAK. 

void __fastcall EditWinlni () 
{ 

AnsiString FileName = "C : WWINDOWSWWIN. INI" ;// set the file name 
Forml->Memol->Lines->LoadFromFile (FileName) ; // load from file 

Forml->Memol->Lmes->SaveToFile (ChangeFileExt (FileName, ".BAK")); // save to backup 

} 

Creazione di un nuovo elenco di stringhe 



Un elenco di stringhe di solito fa parte di un componente. A volte, tuttavia, risulta 
comodo creare elenchi di stringhe indipendenti, ad esempio per memorizzare 
stringhe per una tabella di consultazione. II modo in cui si crea e si gestisce un elenco 
di stringhe dipende dal fatto che l'elenco sia a breve termine (creato, usato e distrutto 
in una singola routine) oppure a lungo termine (disponibile finche l'applicazione non 
viene terminata). Indipendentemente dal tipo di elenco di stringhe creato, al termine 
delle operazioni occorre ricordarsi di liberare la memoria utilizzata. 

Elenchi di stringhe a breve termine 

Se si utilizza un elenco di stringhe solo per la durata di una singola routine, e 
possibile crearlo, utilizzarlo e distruggerlo in un solo posto. Questo e il modo piu 
sicuro per lavorare con elenchi di stringhe. Poiche l'oggetto string list alloca memoria 
per se e per le proprie stringhe, per essere certi che la memoria venga liberata anche 
nel caso si verifichi un'eccezione si dovrebbe utilizzare un blocco try... finally. 

1 Costruire l'oggetto string list. 

2 Nella parte try di un blocco try... finally, utilizzare l'elenco di stringhe. 

3 Nella parte finally, liberare l'oggetto string list. 

II seguente gestore di evento risponde al clic di un pulsante costruendo un elenco di 
stringhe, utilizzandolo, e quindi distruggendolo. 

void __fastcall TForml: :ButtonClickl (TObject *Sender) 

{ 

TStringList *TempList = new TStringList ; // declare the list 
try{ 

//use the string list 

} 

finally { 

delete TempList; // destroy the list object 

} 

} 
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Elenchi di stringhe a lungo termine 

Se un elenco di stringhe deve essere disponibile in un qualunque momenta durante 
l'esecuzione dell'applicazione, costruire l'elenco all'awio dell'applicazione e 
distruggerlo prima che l'applicazione termini. 

1 Nel file unit della scheda principale dell'applicazione, aggiungere un campo di 
tipo TStrings alia dichiarazione della scheda. 

2 Scrivere un costruttore per la scheda principale che viene eseguito prima che la 
scheda appaia. Dovrebbe creare un elenco di stringhe e dovrebbe assegnarlo al 
campo dichiarato al punto precedente. 

3 Scrivere un gestore di evento che liberi l'elenco di stringhe nell'evento OnClose 
della scheda. 

Questo esempio utilizza un elenco di stringhe a lungo termine per registrare i clic che 
l'utente fa con il mouse sulla scheda principale, quindi salva l'elenco in un file prima 
del termine dell'applicazione. 

// 

♦include <vcl.h> 
♦pragma hdrstop 

ftinclude "Unitl.h" 

// 

♦pragma package (smart_init) 
♦pragma resource "*.dfm" 
TForml *Forml; 

// 

__fastcall TForml: : TForml (TComponent* Owner) 
: TForml Owner) 

{ 

ClickList = new TStringList ; 

} 

// 

void fastcall TForml : :FormClose (TObject *Sender, TCloseAction &Action) 

{ 

ClickList->SaveToFile(ChangeFileExt (Application->ExeName, 11 .LOG" )); //Save the list 
delete ClickList; 

} 

// 

void fastcall TForml: :FormMouseDown (TObject *Sender, TMouseButton Button, 

TShiftState Shift, int X, int Y) 

{ 

TVarRec v[] = {X,Y}; 

ClickList->Add (Format ("Click at (%d, %d) ",v,ARRAYSIZE(v) - l));//add a string to the list 

} 
} 

Gestione di stringhe in un elenco 



Le operazioni compiute di solito sugli elenchi di stringhe includono: 
• Conteggio di stringhe in un elenco 
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• Accesso ad una particolare stringa 

• Ricerca della posizione di una stringa nell'elenco 

• Analisi sequenziale di stringhe in un elenco 

• Aggiunta di una stringa a un elenco 

• Spostamento di una stringa all'interno di un elenco 

• Cancellazione di una stringa da un elenco 

• Copia completa di un elenco di stringhe 

Conteggio di stringhe in un elenco 

La proprieta a sola lettura Count restituisce il numero di stringhe nell'elenco. Poiche 
gli elenchi di stringhe utilizzano indici con base zero, il valore di Count e pari 
all'indice dell'ultima stringa piu uno. 

Accesso ad una particolare stringa 

La proprieta array Strings contiene le stringhe dell'elenco, referenziate da un indice 
con base zero. 

StringListl->Strings [0] = "This is the first string."; 

Individuazione di elementi in un elenco di stringhe 

Per individuare una stringa in un elenco di stringhe, utilizzare il metodo IndexOf. 
IndexOf restituisce l'indice della prima stringa nell'elenco che e uguale al parametro 
passatogli, e restituisce -1 se la stringa parametro non viene trovata. IndexOf trova 
solo le corrispondenze esatte; se si desidera cercare una corrispondenza di stringa 
parziale, si deve scrivere del codice che esamini in sequenza l'elenco di stringhe. 

Per esempio, si potrebbe utilizzare IndexOf per determinare se il nome di un certo file 
e presente negli Elements di una casella di riepilogo: 

if (FileListBoxl->Items->IndexOf ("WIN. INI") > -1) ... 

Analisi sequenziale di stringhe in un elenco 

Per esaminare in modo sequenziale le stringhe in un elenco, utilizzare un ciclo for 
che parta da zero e arrivi a Count-1. 

Questo esempio converte ciascuna stringa in una casella di riepilogo in caratteri 
maiuscoli. 

void __fastcall TForml: :ButtonlClick(TObject *Sender) 
{ 

for (int i = 0; i < ListBoxl->Items->Count ; i++) 
ListBoxl->Items->Strings [i] = Uppercase (ListBoxl->Items->Strings [i] ) ; 

} 

Aggiunta di una stringa a un elenco 

Per aggiungere una stringa alia fine di un elenco di stringhe, chiamare il metodo Add, 
passando la nuova stringa come parametro. Per inserire una stringa nell'elenco, 
chiamare il metodo Insert passando due parametri: la stringa e l'indice della 
posizione in cui la si vuole collocare. Per esempio, per fare in modo che la stringa 
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"Three" sia inserita nella terza posizione in un elenco si potrebbe utilizzare 
l'istruzione: 

StringListl->Insert (2, "Three" ) ; 
Per aggiungere le stringhe di un elenco ad un altro, chiamare il metodo AddStrings: 

StringListl->AddStrings (StringList2) ; // append the strings from StringList2 to StringListl 

Spostamento di una stringa aH'interno di un elenco 

Per spostare una stringa in un elenco di stringhe, chiamare il metodo Move passando 
due parametri: l'indice corrente della stringa e l'indice che si vuole assegnare. Per 
esempio, per spostare la terza stringa in un elenco alia quinta posizione si potrebbe 
utilizzare: 

StringList0bject->Move(2, 4); 

Cancellazione di una stringa da un elenco 

Per cancellare una stringa da un elenco di stringhe, chiamare il metodo Delete 
dell'elenco, passando l'indice della stringa che si desidera cancellare. Se non si 
conosce qual e l'indice della stringa che si vuole cancellare, utilizzare il metodo 
IndexOfper individuarlo. Per cancellare tutte le stringhe in un elenco di stringhe, 
utilizzare il metodo Clear. 

Questo esempio utilizza IndexOfe Delete per trovare e cancellare una stringa: 

int BIndex = ListBoxl->Items->IndexOf ( "bureaucracy ") ; 
if (BIndex > -1) 
ListBoxl->ltems->Delete (BIndex) ; 

Copia di un intero elenco di stringhe 

Si puo utilizzare il metodo Assign per copiare le stringhe da un elenco sorgente in un 
elenco di destinazione, sovrascrivendo i contenuti dell'elenco di destinazione. Per 
aggiungere le stringhe senza sovrascrivere l'elenco di destinazione, utilizzare 
AddStrings. Ad esempio: 

Memol->Lines->Assign (ComboBoxl->Item) s; //overwrites original strings 

copia le righe da una casella combinata in un memo (sovrascrivendo il memo), 
mentre 

Memol->Lines->AddStrings (ComboBoxl->Items) , -//appends strings to end 

aggiunge al memo le righe contenute nella casella combinata. 

Quando si fanno copie locali di un elenco di stringhe, utilizzare il metodo Assign. 
Quando si aggiunge una variabile string list ad un'altra — 

StringListl = StringList2 ; 

— l'oggetto string list originale andra perduto, spesso con risultati imprevisti. 

Associazione di oggetti ad un elenco di stringhe 

Oltre alle stringhe memorizzate nella proprieta Strings, un elenco di stringhe puo 
conservare riferimenti a oggetti che vengono memorizzati nella proprieta Objects. 
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Come Strings, anche Objects e un array con un indice a base zero. L'uso piu comune 
di Objects e quello di associare bitmap a stringhe per controlli con tracciamento 
personalizzato. 

Utilizzare i metodi AddObject o InsertObject per aggiungere all'elenco una stringa e un 
oggetto associato in una sola passata. IndexOf Object restituisce l'indice della prima 
stringa nell'elenco che e associata ad un oggetto specificate Metodi come Delete, 
Clear e Move operano contemporaneamente su stringhe e oggetti; ad esempio, la 
cancellazione di una stringa rimuove l'oggetto corrispondente (se ne esiste uno). 

Per associare un oggetto con una stringa esistente, assegnare l'oggetto alia proprieta 
Objects usando lo stesso indice. Non e possibile aggiungere un oggetto senza 
aggiungere prima una stringa corrispondente. 

Operazioni con stringhe 



La libreria runtime BaseCLX fornisce molte routine specialistiche di gestione delle 
stringhe, specifiche per un tipo stringa. Queste sono routine per stringhe wide, Ansi e 
null-terminated (char*). Le routine che hanno a che fare con i tipi null-terminated 
usano la terminazione con null per determinare la lunghezza della stringa. I seguenti 
argomenti forniscono una panoramica su molte routine per la gestione delle string 
incluse nella libreria di esecuzione. 

Routine per wide character 



Le wide string sono utilizzate in un moltissime situazioni. Alcune tecnologie, come 
XML, utilizzano le wide string come tipo nativo. E anche possibile scegliere di 
utilizzare le wide string in quanto semplificano alcune problematiche connesse alia 
gestione delle stringhe in applicazioni che hanno piu ambienti di destinazione. L'uso 
di uno schema di codifica con caratteri estesi offre il vantaggio di poter effettuare 
molte delle solite assunzioni sulle stringhe che non funzionano per i sistemi MBCS. 
C'e una relazione diretta tra il numero di byte della stringa e il suo numero di 
caratteri. Non ci si deve preoccupare di troncare i caratteri a meta o di confondere la 
seconda meta di un carattere con l'inizio di un altro. 

Uno svantaggio nell'utilizzo dei caratteri estesi e che la maggior parte dei controlli 
della VCL rappresentano valori di stringa come stringhe a singolo byte o stringhe 
MBCS . (I controlli CLX di solito utilizzano wide string.) La conversione dal sistema 
wide character al sistema MBCS, e viceversa, ogni volta che si imposta una proprieta 
stringa o se ne legge il valore, richiederebbe notevoli quantita di ulteriore codice e 
rallenterebbe l'applicazione. Tuttavia, puo risultare necessario tradurre in wide 
character alcuni speciali algoritmi di elaborazione delle stringhe che hanno bisogno 
di sfruttare i vantaggi della correlazione 1:1 tra caratteri e WideChars. 

Le seguenti funzioni permettono la conversione tra le stringhe di caratteri standard a 
singolo byte (o stringhe MBCS) e le stringhe Unicode: 

• StringToWideChar 

• WideCharLenToString 
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• WideCharLenToStrVar 

• WideCharToString 

• WideCharToStrVar 

Inoltre, le seguenti funzioni effettuano la traduzione da WideStrings a altre 
rappresentazioni e viceversa: 

• UCS4StringToWideString 

• WideStringToUCS4String 

• VarToWideStr 

• VarToWideStrDef 

Le seguenti routine operano direttamente con WideStrings: 

• WideCompareStr 

• WideCompareText 

• WideSameStr 

• WideSameText 

• WideSameCaption (CLX only) 

• WideFmtStr 

• WideFormat 

• WideLowerCase 

• WideUpperCase 

Infine, alcune routine includono degli overload per operare con le wide string: 

• UniqueString 

• Length 

• Trim 

• TrimLeft 

• TrimRight 

Routine comunemente utilizzate per AnsiStrings 



Le routine di gestione delle AnsiString coprono diverse aree funzionali. All'interno 
di queste aree, alcune vengono usate per lo stesso scopo, differenziandosi solo per il 
fatto che usano o meno un particolare criterio nei calcoli. Le tabelle riportate di 
seguito elencano queste routine suddividendole in queste aree funzionali: 

• Confronto 

• Conversione tra lettere maiuscole/minuscole 

• Modifica 

• Sottostringa 

Quando e possibile, le tabelle forniscono anche le colonne per indicare se una routine 
soddisfa i seguenti criteri. 

• Sensibilita a maiuscole/minuscole: Se si utilizzano le impostazioni locali, 
determina la definizione del formato delle lettere. Se la routine non usa le 
impostazioni locali, l'analisi viene effettuata sui valori ordinali dei caratteri. Se la 
routine tiene con to della differenza tra lettere maiuscole/ minuscole, c'e una 
fusione logica dei caratteri maiuscoli e minuscoli che viene determinata da un 
modello predefinito. 
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• Usa impostazioni locali: L'abilitazione della versione locale consente di 
personalizzare V applicazione per specifiche nazioni, in particolare per gli 
ambienti con lingue dell'Asia. La maggior parte delle versioni nazionalizzate 
considera i caratteri minuscoli minori dei corrispondenti caratteri maiuscoli. 
Questo e in contrasto con l'ordinamento ASCII, nel quale i caratteri minuscoli sono 
maggiori dei caratteri maiuscoli. Le routine che usano le impostazioni locali di 
Windows sono normalmente precedute dalla parola Ansi (cioe, AnsiXXX). 

• Supporta il set di caratteri multibyte (MBCS): I MBCS vengono usati quando si 
scrive codice per paesi dell'estremo oriente. I caratteri multi-byte vengono 
rappresentati come un combinazione di codici di carattere ad uno e a due byte, 
cosicche la lunghezza in byte non corrisponde necessariamente alia lunghezza 
della stringa. Le routine che supportano i MBCS sono scritte per analizzare 
caratteri ad uno e a due byte. 

ByteType e StrByteType determinano se un particolare byte e quello iniziale di un 
carattere di due byte. Quando si usano i caratteri multi-byte bisogna prestare 
attenzione a non troncare una stringa tagliando a meta un carattere di due byte. 
Non si devono passare caratteri come parametro ad una funzione o procedura, 
poiche le dimensioni di un carattere non possono essere predeterminate. Si puo 
passare, invece, un puntatore ad un carattere o ad una stringa. Per ulteriori 
informazioni su MBCS, consultare il paragrafo "Abilitazione del codice 
dell'applicazione" a pagina 16-2 of Capitolo 16, "Creazione di applicazioni 
internazionali". 

Tabella 4.6 Routine per il confronto delle stringhe 

Sensibilita a Usa impostazioni 



Routine 


maiuscole/minuscole 


locali 


Supporta MBCS 


AnsiCompareStr 


Si 


Si 


Si 


AnsiCompareText 


no 


Si 


Si 


AnsiCompareFileName 


no 


Si 


Si 


AnsiMatchStr 


Si 


Si 


yes 


AnsiMatchText 


no 


Si 


Si 


AnsiContainsStr 


Si 


Si 


Si 


AnsiContainsText 


no 


Si 


Si 


AnsiStartsStr 


Si 


Si 


Si 


AnsiStartsText 


no 


Si 


Si 


AnsiEndsStr 


Si 


Si 


Si 


AnsiEndsText 


no 


Si 


Si 


AnsilndexStr 


Si 


Si 


Si 


AnsilndexText 


no 


Si 


Si 


CompareStr 


Si 


no 


no 


CompareText 


no 


no 


no 


AnsiResemblesText 


no 


no 


no 
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Tabella 4.7 Routine di conversione maiuscole/minuscole 
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Routine 






JTi.± LJll — iKJ VV \Zl V — CI J>^. 


Si 


Si 


AnsiLowerCaseFileName 


Si 


Si 


AnsiUpperCaseFileName 


Si 


Si 


AnsiUpperCase 


Si 


Si 


LowerCase 


no 


no 


Uppercase 


no 


no 



Le routine usate per le stringhe dei nomi di file: AnsiCompareFileName, 
AnsiLowerCaseFileNamee AnsiUpperCaseFileName usano tutti le impostazioni locali 
di Windows. Occorre usare sempre nomi di file che siano perfettamente trasportabili, 
dal momento che la lingua (il set di caratteri) usato per questi nomi puo e potrebbe 
differire dall'interfaccia utente predefinita. 



Tabella 4.8 Routine per la modifica di stringhe 

Sensibilita a 
maiuscole/ 




AdjustLineBreaks 


ND 


Si 


AnsiQuotedStr 


ND 


Si 


AnsiReplaceStr 


Si 


Si 


AnsiReplaceText 


no 


Si 


StringReplace 


optional by flag 


Si 


ReverseString 


ND 


no 


StuffString 


ND 


no 


Trim 


ND 


Si 


TrimLeft 


ND 


Si 


TrimRight 


ND 


Si 


WrapText 


ND 


Si 




Tabella 4.9 Routine per le sottostringhe 



Sensibilita a 
maiuscole/ 



AnsiExtractQuotedStr 

AnsiPos 

IsDelimiter 

IsPathDelimiter 

LastDelimiter 



ND 

Si 

Si 

Si 

Si 



Si 
Si 
Si 
Si 
Si 
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Tabella 4.9 Routine per le sottostringhe 



Routine 

LeftStr 
RightStr 
MidStr 
QuotedStr 



Sensibilita a 

maiuscole/ 

minuscole 

ND 
ND 
ND 
no 



Supporta MBCS 



no 
no 
no 
no 



Routine comunemente utilizzate per stringhe terminate con null 

Le routine di gestione delle stringhe terminate con null coprono diverse aree 
funzionali. All'interno di queste aree, alcune vengono usate per lo stesso scopo, 
differenziandosi solo per il fatto che usano o meno un particolare criterio nei calcoli. 
Le tabelle riportate di seguito elencano queste routine suddividendole in queste aree 
funzionali: 

• Confronto 

• Conversione tra lettere maiuscole /minuscole 

• Modifica 

• Sottostringa 

• Copia 

Ove opportune le tabelle forniscono anche colonne che indicano se la routine e 
sensibile alle maiuscole /minuscole, se utilizza l'ambiente corrente e/o supporta i set 
di caratteri multibyte. 

Tabella 4.10 Routine di confronto per stringhe terminate con null 



Routine 


Sensibilita a 


Usa impostazioni 
scole locali 




AnsiStrComp 


Si 


Si 


Si 


AnsiStrlComp 


no 


Si 


Si 


AnsiStrLComp 


Si 


Si 


Si 


AnsiStrLIComp 


no 


Si 


Si 


StrComp 


Si 


no 


no 


StrlComp 


no 


no 


no 


StrLComp 


Si 


no 


no 


StrLIComp 


no 


no 


no 



Tabella 4.11 Routine di conversione maiuscole/minuscole per stringhe terminate con null 

Usa impostazioni 

Routine locali Supporta MBCS 

AnsiStrLower Si Si 

AnsiStrUpper Si Si 
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Tabella 4.11 Routine di conversione maiuscole/minuscole per stringhe terminate con null 



Routine 


Usa impostazioni 


Supporta MBCS 


StrLower 


no 


no 


StrUpper 


no 


no 


Tabella 4.12 Routine per la modifica di stringhe 




Routine 






StrCat 






StrLCat 






Tabella 4.13 Routine per le sottostringhe 




Routine 


Sensibilita a 

maiuscole/ 

minuscole 


Supporta MBCS 


AnsiStrPos 


Si 


Si 


AnsiStrScan 


Si 


Si 


AnsiStrRScan 


Si 


Si 


StrPos 


Si 


no 


StrScan 


Si 


no 


StrRScan 


Si 


no 


Tabella 4.14 Routine per la copia di stringhe 



Routine 

StrCopy 

StrLCopy 

StrECopy 

StrMove 

StrPCopy 

StrPLCopy 



Stampa 



Dal punto di vista strettamente tecnico, la classe TPrinter non appartiene a BaseCLX 
in quanta vi sono due versioni separate, una per la VCL (nella unit Printers) e una per 
la CLX (nella unit QPrinters). L'oggetto TPrinter della VCL incapsula i dettagli delle 
stampanti Windows. L'oggetto TPrinter e un dispositivo per il disegno su stampante. 
Esso genera del codice postscript e lo invia ai dispositivi lpr, lp o a un altro comando 
di stampa. Entrambe le versioni di TPrinter, tuttavia, sono estremamente simili. 

Per ottenere un elenco delle stampanti installate disponibili, utilizzare la proprieta 
Printers. Entrambi gli oggetti printer utilizzano TCanvas (identico al TCanvas della 
scheda), il che significa che tutto cio che puo essere tracciato su una scheda puo anche 
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essere stampato. Per stampare un'immagine, chiamare il metodo BeginDoc seguito da 
un qualsiasi canvas grafico che si desidera stampare (incluso del testo mediante il 
metodo TextOut) e inviare il lavoro alia stampante chiamando il metodo EndDoc. 

L'esempio seguente utilizza un pulsante e un campo memo su una scheda. Quando 
l'utente fa clic sul pulsante, il contenuto del memo viene stampato a una distanza di 
200-pixel dal bordo della pagina. 

Per eseguire con successo questo esempio, includere <Printers.hpp> nel file unit. 

void __fastcall TForml: :ButtonlClick(TObject *Sender) 

{ 

TPrinter *Prntr = Printerf); 

TRect r = Rect (200,200,Prntr->PageWidth - 200, Prntr->PageHeight- 200); 
Prntr->BeginDoc ( ) ; 

for( int i = 0; i < Memol->Lines->Count ; i++) 

Prntr->Canvas->TextOut(200,200 + (i * 
Prntr->Canvas->TextHeight (Memol->Lines->Strings [i] ) ) , 
Memol->Lines->Strings [i] ) ; 
Prntr->Canvas->Brush->Color = clBlack; 
Prntr->Canvas->FrameRect (r) ; 
Prntr->EndDoc() ; 

} 

Per ulteriori informazioni sull'utilizzo dell'oggetto TPrinter, consultare la Guida in 
linea alia voce TPrinter. 

Conversione di misure 



La unit ConvUtils dichiara una funzione Convert di uso generale che e possibile 
utilizzare per convertire una misura da un sistema di misura a uno altro. E possibile 
eseguire conversioni tra unita di misura compatibili come piedi e pollici o giorni e 
settimane. Le unita di misura che misurano lo stesso tipo di cose sono dette 
appartenere alia stessa famiglia di conversione. Le unita che devono essere convertite 
devono appartenere alia stessa famiglia di conversione. Per informazioni su come 
effettuare una conversione, vedere la sezione successiva Esecuzione di conversioni e 
consultare l'argomento Convert nella Guida in linea. 

La unit StdConvs definisce diverse famiglie di conversione e unita di misura 
all'interno di ogni famiglia. Inoltre, e possibile creare famiglie di conversione 
personalizzate e le relative unita di misura utilizzando le funzioni 
RegisterConversionType e RegisterConversionFamily.Per informazioni sull'ampliamento 
delle conversioni e sulle unita di conversione, consultare la sezione Aggiunta di 
nuovi tipi di misura e consultare l'argomento Convert nella Guida in linea. 

Esecuzione di conversioni 



E possibile utilizzare la funzione Convert per eseguire conversioni sia semplici che 
complesse. La funzione ha una sintassi semplificata e una seconda sintassi per 
l'esecuzione di conversioni tra tipi di misura complessi. 
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Esecuzione di conversioni semplici 

E possibile utilizzare la funzione Convert per convertire una misura da un insieme di 
unita a un altro. La funzione Convert serve per convertire unita di misura che 
misurano lo stesso tipo di cose (distanze, superfici, tempo, temperature e cosi via). 

Per utilizzare Convert, e necessario specificare le unita di misura da cui convertire e in 
cui convertire. Si utilizza il tipo TConvType per identificare le unita di misura. 

Ad esempio, queste istruzioni convertono una temperatura da gradi Fahrenheit a 
gradi Kelvin: 

TempInKelvin = Convert (StrToFloat (Editl->Text) , tuFahrenheit , tuKelvm) ; 

Esecuzione di conversioni complesse 

E possibile utilizzare la funzione Convert anche per eseguire conversioni piu 
complesse tra il rapporto di due tipi di misura. Un esempio della necessita di 
ricorrere a questo tipo di conversione potrebbe essere la conversione da miglia orarie 
a metri al minuto per il calcolo della velocita oppure la conversione da galloni al 
minuto a litri per ora per il calcolo del flusso. 

Ad esempio, la seguente chiamata converte da miglia per gallone in chilometri per 
litro: 

double nKPL = Convert (StrToFloat (Editl. Text) , duMiles, vuGallons, duKilometers , vuLiter) ; 

Le unita di misura che devono essere convertite devono appartenere alia stessa 
famiglia di conversione (devono misurare la stessa cosa). Se le unita di misura non 
sono compatibili, Convert solleva un'eccezione EConversionError. E possibile 
controllare se due valori TConvType appartengono alia stessa famiglia di conversione 
chiamando CompatibleConversionTypes. 

La unit StdConvs definisce diverse famiglie di valori TConvType. Per una lista delle 
famiglie predefinite di unita di misura e delle unita di misura in ogni famiglia, 
consultare l'argomento "Conversion family variables" nella Guida in linea. 

Aggiunta di nuovi tipi di misura 



Se si vogliono eseguire conversioni tra unita di misura che non sono definite nella 
unit StdConvs, e necessario creare una nuova famiglia di conversione per 
rappresentare le unita di misura (valori TConvType). Se due valori TConvType sono 
registrati con la stessa famiglia di conversione, la funzione Convert puo effettuare la 
conversione di misurazioni fatte utilizzando le unita di misura rappresentate da quei 
valori TConvType. 

Per prima cosa e necessario ottenere i valori TConvFamily mediante la registrazione di 
una famiglia di conversione utilizzando la funzione RegisterConversionFamily. Dopo 
avere ottenuto un valore TConvFamily (registrando una nuova famiglia di 
conversione o utilizzando una delle variabili globali nella unit StdConvs), e possibile 
utilizzare la funzione RegisterConversionType per aggiungere le nuove unita di misura 
alia famiglia di conversione. Gli esempi seguenti mostrano come fare. 
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Creazione di una semplice famiglia di conversione e aggiunta delle 
unite 



Un esempio della necessita di creare una nuova famiglia di conversione e aggiungere 
nuovi tipi di unita di misura potrebbe essere la conversione fra lunghi periodi 
temporali (ad esempio, da mesi a secoli) in cui potrebbe verificarsi una perdita di 
precisione. 

Per approfondire il problema, la famiglia cbTime utilizza come unita di misura di 
base il giorno. L'unita di misura di base e quella che viene utilizzata per eseguire 
tutte le conversioni all'interno di quella famiglia. Quindi, tutte le conversioni devono 
essere fatte in termini di giorni. Quando si eseguono conversioni utilizzando come 
unita di misura i mesi o una unita maggiore (anni, decenni, secoli, millenni) 
potrebbero verificarsi delle inesattezze perche non esiste una conversione esatta tra 
giorni e mesi, giorni e anni, e cosi via. I mesi hanno varie lunghezze; gli anni hanno 
fattori di correzione per scarti di anni, di secondi, e cosi via. 

Se si utilizzano solo unita di misura maggiori o uguali ai mesi, e possibile creare una 
famiglia di conversione piu precisa che utilizza gli anni come unita di misura di 
base.Questo esempio crea una nuova famiglia di conversione di nome cbLongTime. 

Dichiarazione delle variabili 

Per prima cosa e necessario dichiarare le variabili per gli identificativi. Gli 
identificativi sono utilizzati nella nuova famiglia di conversione LongTime e nelle 
unita di misura che sono membri della famiglia: 

tConvFamily cbLongTime; 
TConvType ltMonths; 
TConvType It Years; 
TConvType ltDecades; 
TConvType ltCenturies ; 
TConvType ltMillennia; 

Registrazione della famiglia di conversione 

Poi, si deve registrare la famiglia di conversione: 

cbLongTime = RegisterConversionFamily ("Long Times"); 

Benche sia disponibile una procedura UnregisterConversionFamily, non e necessario 
annullare la registrazione di famiglie di conversione a meno che la unit che le 
definisce non venga rimossa in fase di esecuzione. Esse vengono automaticamente 
annullate quando si chiude l'applicazione. 

Registrazione delle unita di misura 

Poi, e necessario registrare le unita di misura all'interno della famiglia di conversione 
appena creata. Si utilizza la funzione Register ConversionType, che registra le unita di 
misura all'interno di una determinata famiglia. E necessario definire l'unita di misura 
di base, che nell'esempio e l'anno, e le altre unita di misura vengono definite 
utilizzando un fattore che indica la loro relazione con l'unita di misura di base. Cosi, 
il fattore per ltMonths e 1/12 perche l'unita di misura di base per la famiglia 
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LongTime e l'anno. Includere anche una descrizione delle unita di misura verso cui si 
converte. 

II codice per registrare le unita di misura e riportato di seguito: 

ltMonths = RegisterConversionType (cbLongTime, "Months" , 1/12 ) ; 
ltYears = RegisterConversionType(cbLongTime, "Years", 1) ; 
ltDecades = RegisterConversionType (cbLongTime, "Decades", 10) ; 
ItCenturies = RegisterConversionType (cbLongTime, "Centuries", 100) ; 
ltMillennia = RegisterConversionType (cbLongTime, "Millennia" , 1000) ; 

Utilizzo delle nuove unita di misura 

A questo punto e possibile utilizzare le unita di misura appena registrate per 
eseguire una conversione. La funzione globale Convert puo effettuare la conversione 
tra tutti i tipi di conversione registrati con la famiglia di conversione cbLongTime. 

Pertanto, invece di utilizzare la seguente chiamata a Convert, 

Convert (StrToFloat (Editl->Text ) , tuMonths, Millennia) ; 
e possibile utilizzare ora questa chiamata per una maggior precisione: 

Convert (StrToFloat (Editl->Text ) , ltMonths, ltMillennia) ; 

Utilizzo di una funzione di conversione 



Nei casi in cui la conversione e piu complessa, invece di utilizzare un fattore di 
conversione, e possibile utilizzare una sintassi diversa e specificare una funzione che 
esegue la conversione. Ad esempio, e impossibile convertire valori di temperatura 
utilizzando un fattore di conversione, perche le varie scale termometriche hanno 
origini differenti. 

Questo esempio, che deriva dalla unit StdConvs, mostra come registrare un tipo di 
conversione mediante la preparazione di funzioni per la conversione in entrambi i 
sensi a partire dall'unita di misura di base. 

Dichiarazione delle variabili 

Per prima cosa, dichiarare le variabili per gli identificativi. Gli identificativi sono 
utilizzati nella famiglia di conversione cbTemperature e nelle unita di misura che sono 
membri della famiglia: 

TConvFamily cbTemperature; 
TConvType tuCelsius; 
TConvType tuKelvm; 
TConvType tuFahrenheit ; 

Le unit di misura elencata di seguito sono un sottoinsieme delle unita di misura della 
temperatura effettivamente registrate nella unit StdConvs. 

Registrazione della famiglia di conversione 

Poi, si deve registrare la famiglia di conversione: 

cbTemperature = RegisterConversionFamily ("Temperature"); 
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Registrazione dell'unita di misura di base 

Poi, definire e registrare l'unita di misura di base della famiglia di conversione, che 
nell'esempio sono i gradi Celsius. Notare che, nel caso dell'unita di misura di base, si 
puo utilizzare un fattore di conversione semplice, perche non c'e alcuna conversione 
effettiva da fare: 

tuCelsius = RegisterConversionType(cbTemperature, "Celsius", 1) ; 

Scrittura dei metodi per la conversione in base all'unita di misura di base 

E necessario scrivere il codice che esegue la conversione da ogni scala termometri a 
gradi Celsius e viceversa, perche queste conversioni non utilizzano su un semplice 
fattore di conversione. Queste funzioni sono prese dalla unit StdConvs: 

double __fastcall FahrenheitToCelsius (const double AValue) 

return ( ( (AValue - 32) * 5) / 9) ; 

double __fastcall CelsiusToFahrenheit (const double AValue) 

return ( ( (AValue * 9 ) / 5 ) + 32); 

double __fastcall KelvinToCelsius (const double AValue) 

return (AValue - 273.15) ; 

double „fastcall CelsiusToKelvin (const double AValue) 
return (AValue + 273.15) ; 



Registrazione delle altre unita di misura 

Ora che si hanno le funzioni di conversione, e possibile registrare le altre unita di 
misura all'interno della famiglia di conversione. Includere anche una descrizione 
delle singole unita di misura. 

II codice per registrare le altre unita di misura nella famiglia e riportato di seguito: 

tuKelvin = RegisterConversionType (cbTemperature, "Kelvin", KelvinToCelsius, 
CelsiusToKelvin) ; 

tuFahrenheit = RegisterConversionType (cbTemperature, "Fahrenheit", FahrenheitToCelsius, 
CelsiusToFahrenheit) ; 

Utilizzo delle nuove unita di misura 

A questo punto e possibile utilizzare le unita di misura appena registrate per 
eseguire le conversioni nelle applicazioni. La funzione globale Convert puo effettuare 
la conversione tra tutti i tipi di conversione registrati con la famiglia di conversione 
cbTemperature. Ad esempio il codice seguente converte un valore da gradi Fahrenheit 
a gradi Kelvin. 

Convert (StrToFloat (Editl->Text) , tuFahrenheit, tuKelvin); 
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Utilizzo di una classe per gestire le conversioni 

E sempre possibile utilizzare funzioni di conversione per registrare una unita di 
conversione. A volte, pero, l'operazione richiede la creazione di un numero 
spropositato di funzioni che fanno tutte essenzialmente la stessa cosa. 

Se fosse possibile scrivere un set di funzioni di conversione che si differenziano solo 
per il valore di un parametro o di una variabile, sarebbe possibile creare una classe 
per gestire quelle conversioni. Ad esempio, dall'introduzione dell'Euro e stata 
approntata una serie di tecniche standard per la conversione delle diverse valute 
europee. Sebbene il fattore di conversione rimanga costante (a differenza del fattore 
di conversione, per esempio, tra dollaro e euro), e impossibile utilizzare un semplice 
fattore di conversione per effettuare correttamente la conversione tra valute europee 
per due motivi: 

• La conversione deve arrotondare a un numero di cifre specifico per la valuta. 

• La tecnica che si appoggia al fattore di conversione utilizza un fattore inverso 
rispetto a quello specificato dalle conversioni standard per l'Euro. 

Tuttavia, tutto questo puo essere gestito dalle funzioni di conversione come in questo 
caso: 

double __fastcall FromEuro (const double AValue, const double Factor, TRoundToRange FRound) 

{ 

return (RoundTo (AValue * Factor, FRound)); 

} 

double __fastcall ToEuro (const double AValue, const double Factor) 

{ 

return (AValue / Factor) ; 

} 

II problema e che questo approccio richiede dei parametri aggiuntivi per la funzione 
di conversione, il che significa che e impossibile semplicemente registrare la stessa 
funzione per ogni valuta europea. Per evitare di dovere scrivere due nuove funzioni 
di conversione per ogni valuta europea, e possibile utilizzare le stesse due funzioni 
trasformandole in membri di una classe. 

Creazione della classe di conversione 

La classe deve essere un discendente di TConvTypeFactor. TConvTypeFactor definisce 
due metodi, ToCommon e FromCommon, per la conversione in entrambi i sensi delle 
unita di misura di base di una famiglia di conversione (in questo caso, da e in Euro). 
Come nel caso delle funzioni che si utilizzano direttamente quando si registra 
un'unita di conversione, questi metodi non hanno alcun parametro aggiuntivo e 
pertanto e necessario fornire, sotto forma di membri privati della classe di 
conversione, il numero di cifre per l'arrotondamento e il fattore di conversione. Lo si 
puo vedere nell'esempio EuroConv nella directory demos \ConvertIt (vedere 
euroconv.pas): 

class PASCALIMPLEMENTATION TConvTypeEuroFactor : public Convutils :: TConvTypeFactor 
{ 

private : 
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TRoundToRange FRound; 
public : 

__fastcall TConvTypeEuroFactor (const TConvFamily AConvFamily, 

const AnsiString ADescription, const double AFactor, const TRoundToRange ARound) ; 
TConvTypeFactor (AConvFamily, ADescription, AFactor); 
virtual double ToCommon (const double AValue); 
virtual double FromCommon (const double AValue); 

} 

II costruttore assegna dei valori a questi membri privati: 

__fastcall TConvTypeEuroFactor: : TConvTypeEuroFactor (const TConvFamily AConvFamily, 

const AnsiString ADescription, const double AFactor, const TRoundToRange ARound) : 
TConvTypeFactor (AConvFamily, ADescription, AFactor); 

{ 

FRound = ARound; 

} 

Le due funzioni di conversione si limitano a utilizzare questi membri privati: 

virtual double TConvTypeEuroFactor: : ToCommon (const double AValue) 
{ 

return (RoundTo (AValue * Factor, FRound)); 

} 

virtual double TConvTypeEuroFactor: : ToCommon (const double AValue) 

{ 

return (AValue / Factor) ; 

} 



Dichiarazione delle variabili 

Ora che si ha una classe di conversione, come nel caso delle altre famiglie di 
conversione, si inizia con la dichiarazione degli identificatori: 



TConvFamily cbEuro; 



TConvType euEUR 
TConvType euBEF 
TConvType euDEM 
TConvType euGRD 
TConvType euESP 
TConvType euFFR 
TConvType euIEP 
TConvType euITL 
TConvType euLUF 
TConvType euNLG 
TConvType euATS 
TConvType euPTE 
TConvType euFIM 



EU euro 

Belgian francs 
German marks 
Greek drachmas 
Spanish pesetas 
French francs 
Irish pounds 
Italian lire 
Luxembourg francs 
Dutch guilders 
Austrian schillings 
Protuguese escudos 
Finnish marks 



Registrazione della famiglia di conversione e delle altre unita 

A questo punto e possibile registrare la famiglia di conversione e le unita valutarie 
europee, utilizzando la nuova classe di conversione. Registrare la famiglia di 
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conversione nello stesso modo con cui sono state registrate le altre f amiglie di 
conversione: 

cbEuro = RegisterConversionFamily ("European currency"); 

Per registrare ogni tipo di conversione, creare un'istanza della classe di conversione 
che rifletta le proprieta del fattore di conversione e arrotondando di quella valuta e 
chiamare il metodo RegisterConversionType: 

TConvTypelnfo *pInfo = new TConvTypeEuroFactor (cbEuro, "EUEuro", 1.0, -2); 
if (! RegisterConversionType (plnfo, euEUR) ) 
delete plnfo; 

plnfo = new TConvTypeEuroFactor (cbEuro, "BelgianFrancs" , 40.3399, 0); 
if (! RegisterConversionType (plnfo, euBEF) ) 
delete plnfo; 

plnfo = new TConvTypeEuroFactor (cbEuro, "GermanMarks" , 1.95583, -2); 
if ( IRegisterConversionType (plnfo, euDEM) ) 
delete plnfo; 

plnfo = new TConvTypeEuroFactor (cbEuro, "GreekDrachmas", 340.75, 0); 
if ( IRegisterConversionType (plnfo, euGRD) 
delete plnfo; 

plnfo = new TConvTypeEuroFactor (cbEuro, "SpanishPesetas" , 166.386, 0); 
if ( IRegisterConversionType (plnfo, euESP) 
delete plnfo; 

plnfo = new TConvTypeEuroFactor (cbEuro, "FrenchFrancs" , 6.55957, -2); 
if ( IRegisterConversionType (plnfo, euFFR) 
delete plnfo; 

plnfo = new TConvTypeEuroFactor (cbEuro, "IrishPounds" , 0.787564, -2); 
if ( IRegisterConversionType (plnfo, euIEP) 
delete plnfo; 

plnfo = new TConvTypeEuroFactor (cbEuro, "ItalianLire" , 1936.27, 0); 
if ( IRegisterConversionType (plnfo, euITL) 
delete plnfo; 

plnfo = new TConvTypeEuroFactor (cbEuro, "LuxembourgFrancs" , 40.3399, -2); 
if ( IRegisterConversionType (plnfo, euLUF) 
delete plnfo; 

plnfo = new TConvTypeEuroFactor (cbEuro, "DutchGuilders", 2.20371, -2); 
if ( IRegisterConversionType (plnfo, euNLG) 
delete plnfo; 

plnfo = new TConvTypeEuroFactor (cbEuro, "AutstrianSchillings" , 13.7603, -2); 
if ( IRegisterConversionType (plnfo, euATS) 
delete plnfo; 

plnfo = new TConvTypeEuroFactor (cbEuro, "PortugueseEscudos" , 200.482, -2); 
if ( IRegisterConversionType (plnfo, euPTE) 
delete plnfo; 

plnfo = new TConvTypeEuroFactor (cbEuro, "FmnishMarks", 5.94573, 0); 
if ( IRegisterConversionType (plnfo, euFIM) 
delete plnfo; 
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Utilizzo delle nuove unita di misura 

A questo punto e possibile utilizzare le unita di misura appena registrate per 
eseguire le conversioni nelle applicazioni. La funzione globale Convert pud effettuare 
la conversione tra tutti i tipi di valuta europei registrati con la nuova famiglia cbEuro. 
Ad esempio, il seguente codice converte un valore da Lire italiane a Marchi tedeschi: 

Edit2->Text = FloatToStr (Convert (StrToFloat (Editl->Text ) , euITL, euDEM) ) ; 

Creazione di spazi di disegno 



L'oggetto TCanvas incapsula un contesto di dispositivo Windows nella VCL, e un 
dispositivo di tracciamento (Qt painter) nella CLX. Gestisce tutte le operazioni di 
disegno per le schede, per i contenitori visuali (come i pannelli) e per l'oggetto 
printer (trattato in "Stampa" a pagina 4-26). Utilizzando l'oggetto canvas, voi ci si 
dovra piu preoccupare di istanziando penne, pennelli, tavolozze e quant'altro. 
L'allocazione e la deallocazione sono gestite automaticamente. 

TCanvas include moltissime routine grafiche primitive per disegnare linee, figure, 
poligoni, caratteri, ecc. su qualsiasi controllo che contenga un canvas. Ad esempio, di 
seguito e riportato un gestore di evento di un pulsante che traccia una linea 
dall'angolo superiore sinistra al centra della scheda e scrive sulla scheda del testo 
non formattato: 

void __fastcall TForml: :ButtonlClick(TObject *Sender) 
{ 

Canvas->Pen->Color = clBlue; 
Canvas->MoveTo( 10, 10 ) ; 
Canvas ->LineTo ( 100, 100 ) ; 
Canvas->Brush->Color = clBtnFace; 
Canvas->Font->Name = "Arial"; 

Canvas->TextOut ( Canvas->PenPos .x, Canvas->PenPos .y, "This is the end of the line" ) ; 

} 

Nelle applicazioni Windows, l'oggetto TCanvas mette al riparo anche da comuni 
errori di grafica di Windows, come il ripristino di contesti di dispositivo, penne, 
pennelli, e cosi via, al valore che avevano prima dell'operazione di disegno. TCanvas 
e utilizzato in C++Builder ovunque sia necessario o possibile disegnare, e rende la 
grafica in Windows semplice e a prova di errore. 

Per un elenco completo delle proprieta e dei metodi, consultare la Guida di 
riferimento in linea alia voce TCanvas. 
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Operazioni con componenti 

Molti componenti sono disponibili all'intemo dell'ambiente di sviluppo nella 
tavolozza Component. I componenti vengono selezionati dalla Component palette e 
rilasciati sulla scheda oppure sul modulo dati. Si progetta l'interfaccia utente 
dell'applicazione organizzando componenti visuali, come pulsanti e caselle di 
riepilogo, su una scheda. E possibile anche collocare componenti non visuali, come i 
componenti di accesso ai dati, o su una scheda osuun modulo dati. 

Ad un primo sguardo, i componenti di C++Builder assomigliano a qualsiasi altra 
classe di C++. Ma ci sono delle differenze tra i componenti di C++Builder e le 
gerarchie standard delle classi di C++ con cui lavora la maggior parte dei 
programmatori C++. Eccone alcune: 

• Tutti i componenti di C++Builder discendono da TComponent. 

• I componenti nella maggioranza dei casi vengono usati cosi come sono e vengono 
modificati tramite le loro proprieta, anziche essere utilizzati come "classi base" da 
cui derivare sottoclassi da aggiungere o di cui modificare le funzionalita. 
Normalmente un componente viene ereditato per aggiungere codice specifico alle 
funzioni membro esistenti di gestione degli eventi. 

• I componenti possono essere allocati solo nello heap, e non nello stack (devono cioe 
essere creati con l'operatore new). 

• Le proprieta dei componenti contengono essenzialmente informazioni da 
utilizzare in fase di esecuzione. 

• I componenti possono essere aggiunti alia Component palette nell'interfaccia 
utente di C++Builder e manipolati su una scheda. 

Spesso i componenti raggiungono un grado di incapsulamento migliore di quello 
solitamente disponibile nelle classi standard di C++. Ad esempio, si consideri 
l'utilizzo di una finestra di dialogo che contiene un pulsante. In un programma 
Windows sviluppato utilizzando componenti della VCL, quando l'utente fa clic sul 
pulsante, il sistema genera un messaggio WM_LBUTTONDOWN. II programma 
deve intercettare questo messaggio (normalmente in un'istruzione switch, in una 
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mappa di messaggi o in una tabella di risposta) e inviarlo ad una routine che viene 
eseguita in risposta al messaggio. 

La maggior parte dei messaggi Windows (VCL) o degli eventi di sistema (CLX) sono 
gestiti dai componenti di C++Builder. Quando si vuole rispondere ad un messaggio, 
occorre solo fornire un gestore di eventi. 

II Capitolo 8, "Sviluppo dell'interfaccia utente dell'applicazione", fornisce 
informazioni dettagliate sull'uso delle schede, come la creazione di schede modali in 
maniera dinamica, il passaggio dei parametri alle schede e il recupero dei dati dalle 
schede. 

Impostazione delle proprieta dei componenti 



Le proprieta rese pubbliche possono essere impostate in fase di progetto nell'Object 
Inspector e, in alcuni casi, con speciali editor di proprieta. Per impostare le proprieta 
in fase di esecuzione, assegnare i nuovi valori nel codice sorgente dell'applicazione. 

Per informazioni sulle proprieta di ciascun componente, consultare la Guida in linea. 

Impostazione delle proprieta in progettazione 



Quando si seleziona un componente su una scheda in fase di progettazione, l'Object 
Inspector visualizza le proprieta rese pubbliche e (se possibile) consente di 
modificarle. Utilizzare il tasto Tab per passare dalla colonna Proprerty left-hand alia 
colonna Value right-hand. Quando il cursore e nella colonna Property, e possibile 
spostarsi a qualsiasi proprieta scrivendo le prime lettere del suo nome. Per proprieta 
di tipo Boolean o enumerativo, e possibile scegliere i valori da un elenco a discesa o 
commutare l'impostazione proposta facendo doppio clic sulla colonna Value. 

Se accanto al nome di una proprieta appare un simbolo piu (+), facendo clic su di 
esso, o digitando il tasto '+' mentre la proprieta ha il fuoco, viene visualizzato un 
elenco di possibili sottovalori per la proprieta. Analogamente, se accanto al nome 
della proprieta viene visualizzato un segno meno ( - ), facendo clic sul simbolo meno, 
o digitando il tasto ' -', i sottovalori vengono nascosti. 

Per impostazione predefinita, le proprieta elencate nella categoria Legacy non 
vengono visualizzate; per modificare i filtri di visualizzazione, fare clic destro 
nell'Object Inspector e scegliere il comando View. Per maggiori informazioni, 
consultare l'argomento "property categories" nella Guida in linea. 

Nel caso siano selezionati piu componenti, l'Object Inspector visualizza tutte le 
proprieta-tranne Name-che sono condivise dai componenti selezionati. Se il valore di 
una proprieta condivisa e diversa tra i componenti scelti, l'Object Inspector 
visualizza il valore predefinito oppure il valore del primo componente selezionato. 
Se si modifica una proprieta condivisa, la modifica viene applicata a tutti i 
componenti scelti. 

Cambiando le proprieta relative al codice, come il nome di un gestore di eventi, 
nell'Object Inspector viene modificato automaticamente il corrispondente codice 
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sorgente. Inoltre, le modifiche apportate al codice sorgente, come la ridenominazione 
di un metodo gestore di eventi in una dichiarazione di classe di una scheda, si 
riflettono immediatamente nell'Object Inspector. 

Utilizzo di editor di proprieta 

Alcune proprieta, come Font, hanno editor di proprieta speciali. Tali proprieta 
mostrano un simbolo di ellissi (...). accanto ai rispettivi valori quando le si seleziona 
nell'Object Inspector. Per aprire l'editor di proprieta, fare doppio clic sulla colonna 
Value oppure fare clic sul simbolo di ellissi, oppure ancora premere la combinazione 
di tasti Ctrl+lnvio quando il fuoco e sulla proprieta o sul suo valore. Con alcuni 
componenti, l'editor di proprieta si apre anche facendo doppio clic sul componente 
collocato sulla scheda. 

Gli editor di proprieta consentono di impostare proprieta complesse mediante una 
sola finestra di dialogo. Sono in grado inoltre di convalidare i dati immessi e spesso 
consentono di visualizzare in anteprima il risultato di un'assegnazione. 

Impostazione di proprieta in esecuzione 



Ogni proprieta modificabile puo essere impostata in corso di esecuzione dal codice 
sorgente. Per esempio, e possibile assegnare dinamicamente un titolo a una scheda: 

Forml->Caption = MyStrmg; 

Chiamate a metodi 



I metodi vengono chiamati come qualsiasi altra comune procedura o funzione. Per 
esempio, i controlli visuali hanno un metodo Repaint che aggiorna l'immagine del 
controllo sullo schermo. II metodo Repaint di un oggetto draw-grid potrebbe essere 
chiamato nel seguente modo: 

DrawGridl->Repaint ; 

Come per le proprieta, il campo d'azione del un nome di metodo determina la 
necessita o meno di qualificatori. Se, per esempio, si desidera ridisegnare una scheda 
dall'interno di un gestore di evento di un controllo figlio della scheda, non e 
necessario anteporre il nome della scheda alia chiamata al metodo: 

void __fastcall TForml: :ButtonlClick(TObject *Sender) 
{ 

Repaint; 

} 

Operazioni con eventi e gestori di evento 



In C++ Builder, quasi tutto il codice che si scrive viene eseguito, direttamente o 
indirettamente, in risposta ad eventi. Un evento e un tipo speciale di proprieta che 
rappresenta un avvenimento in esecuzione, spesso un'azione dell'utente. II codice 
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che risponde direttamente a un evento-detto gestore di evento-e una procedure object. 
Le sezioni che seguono mostrano come: 

• Generare un nuovo gestore di evento. 

• Generare un gestore per l'evento predefinito di un componente. 

• Individuare i gestori di evento. 

• Associare un evento con un gestore di evento esistente. 

• Associare gli eventi di menu con i gestori di evento. 

• Cancellare i gestori di evento. 

Generazione di nuovo gestore di evento 



C++Builder e in grado di generare bozze di gestori di evento per schede ed altri 
componenti. Per creare un gestore di evento: 

1 Selezionare un componente. 

2 Fare clic sul separatore Events nell'Object Inspector. La pagina Events dell'Object 
Inspector visualizzera tutti gli eventi definiti per il componente. 

3 Selezionare l'evento desiderato, quindi fare doppio clic sulla colonna Value 
oppure premerla combinazione di tasto Ctrl+lnvio. 

4 Scrivere il codice che si desidera venga eseguito al verificarsi dell'evento. 

Generazione di un gestore per l'evento predefinito di un componente 



Alcuni componenti hanno un evento predefinito, che e l'evento che il componente 
dovra gestire piu spesso. Per esempio, l'evento predefinita di un pulsante e OnClick. 
Per creare un gestore di evento predefinito, fare doppio clic sul componente nel 
modulo di impostazione della scheda; l'operazione genera una procedura ridotta di 
gestione dell'evento, apre l'editor di codice e colloca il cursore nel corpo della 
procedura, dove si potra aggiungere facilmente il codice necessario. 

Non tutti i componenti hanno un evento predefinito. Alcuni componenti, come 
TBevel, non rispondono a nessun evento. Altri componenti rispondono in modo 
differente quando si fa doppio clic su di essi Form Designer. Per esempio, molti 
componenti, quando si fa doppio clic su di essi in fase di progettazione, aprono un 
editor di proprieta predefinito oppure un'altra finestra di dialogo. 

Individuazione dei gestori di evento 



Se per un certo componente e stato generato un gestore di evento predefinito, 
facendo doppio clic su di esso nel Form Designer, e possibile individuare quel 
gestore di evento nello stesso modo. Facendo doppio clic sul componente verra 
attivato l'editor di codice e il cursore verra collocato all'inizio del corpo del gestore di 
evento. 

Per individuare un gestore di evento che non quello predefinito: 
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1 Selezionare sulla scheda il componente di cui si vuole individuare il gestore di 
evento. 

2 Nell'Object Inspector, fare clic sul separatore Events. 

3 Selezionare l'evento di cui si desidera visualizzare il gestore e fare doppio clic 
sulla colonna Value. Verra aperto il Code editor con il cursore posizionato 
all'inizio del corpo del gestore di evento. 

Associazione di un evento ad un gestore di evento esistente 



Si potrebbe riutilizzare il codice scrivendo gestori di evento che rispondono a piu di 
un evento. Ad esempio, molte applicazioni hanno pulsanti di scelta rapida che 
svolgono funzioni equivalenti ai comandi dei menu a comparsa. Se un pulsante 
attiva la stessa azione di un comando di menu, e possibile scrivere un singolo gestore 
di evento e assegnarlo all'evento OnClick sia del pulsante sia dell'elemento di menu. 

Per associare un evento ad un gestore di evento esistente: 

1 Sulla scheda, selezionare il componente di cui si desidera gestire l'evento. 

2 Sulla pagina Events dell'Object Inspector, selezionare l'evento a cui si desidera 
associare un gestore. 

3 Fare clic sulla freccia verso il basso nella colonna Value accanto all'evento per 
aprire un elenco di gestori di evento scritti in precedenza. (L'elenco include 
solamente i gestori di evento scritti per eventi con lo stesso nome sulla stessa 
scheda). Selezionare dall'elenco un gestore di evento facendo clic sul nome. 

La procedura appena descritta rappresenta un modo molto semplice per riutilizzare i 
gestori di evento. Le liste di azioni , e nella VCL, le bande di azioni, comunque, mettono 
a disposizioni strumenti molto potenti per organizzare in modo centralizzato il 
codice che risponde ai comandi dell'utente. Le liste di azioni possono essere 
utilizzate in applicazioni multipiattaforma, al contrario delle bande di azioni. Per 
ulteriori informazioni su liste e bande di azioni, consultare "Organizzazione delle 
azioni per barre e menu" a pagina 8-17. 

Utilizzo del parametro Sender 

In un gestore di evento, il parametro Sender indica quale componente ha ricevuto 
l'evento ed ha, pertanto, chiamato il gestore. Talvolta risulta utile per far si che 
diversi componenti condividano uno stesso gestore di evento che si comporta in 
modo differente a seconda del componente che lo ha chiamato. E possibile fare cio 
utilizzando il parametro Sender. 

Visualizzazione e codifica di eventi condivisi 

Quando i componenti condividono eventi, e possibile visualizzare gli eventi 
condivisi nell'Object Inspector. Per prima cosa, selezionare i componenti in Form 
Designer tenendo premuto il tasto Maiusc e facendo clic su di essi; quindi scegliere 
nell'Object Inspector la pagina Events. Dalla colonna Value nell'Object Inspector, a 
questo punto e possibile creare un nuovo gestore di evento per alcuni degli eventi 
condivisi oppure assegnare ad essi un gestore di evento. 
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Operazioni con eventi e gestori di evento 

Associazione di eventi di menu a gestori di evento 



II Menu Designer, in combinazione con i componenti MainMenu e PopupMenu, 
semplifica l'utilizzo nell'applicazione di menu a discesa e popup. Comunque, per 
essere operative ciascun elemento di menu deve rispondere all'evento OnClick che si 
verifica ogni qualvolta l'utente sceglie l'elemento di menu oppure preme i tasti 
acceleratori o i tasti scorciatoia ad esso associati. Questa sezione spiega come 
associare i gestori di evento agli elementi di menu. Per informazioni su Menu 
Designer e sui componenti correlati, consultare la sezione "Creazione e gestione dei 
menu" a pagina 8-32. 

Per creare un gestore di evento per una voce di menu: 

1 Aprire il Menu Designer facendo doppio clic su un oggetto MainMenu o 
PopupMenu. 

2 Selezionare nel Menu Designer un elemento del menu. Nell'Object Inspector, 
verificare che sia stato assegnato un valore alia proprieta Name dell'elemento. 

3 Dal Menu Designer, fare doppio clic sull'elemento del menu. C++Builder genera 
un gestore di evento nell'editor di codice. 

4 Srivere il codice che si desidera venga eseguito quando l'utente seleziona il 
comando del menu. 

Per associare un elemento del menu con un gestore di evento OnClick esistente: 

1 Aprire il Menu Designer facendo doppio clic su un oggetto MainMenu o 
PopupMenu. 

2 Selezionare nel Menu Designer un elemento del menu. Nell'Object Inspector, 
verificare che sia stato assegnato un valore alia proprieta Name dell'elemento. 

3 Sulla pagina Events dell'Object Inspector, fare clic sulla freccia verso il basso nella 
colonna Value accanto a OnClick per aprire un elenco dei gestori di evento scritti in 
precedenza. (L'elenco include solamente i gestori di evento scritti per gli eventi 
OnClick della scheda in oggetto). Effettuare una scelta nell'elenco facendo clic su 
un nome di gestore di evento. 

Cancellazione di gestori di evento 



Quando si cancella un componente da una scheda utilizzando il Form Designer, 
C++Builder rimuove il componente dalla dichiarazione dei tipi della scheda. 
Tuttavia, non cancella alcun metodo associato dal file unit, poiche questi metodi 
potrebbero essere chiamati ancora da altri componenti sulla scheda. E possibile 
cancellare manualmente un metodo,come un gestore di evento,ma, in questo caso, 
occorre accertarsi di cancellare sia la dichiarazione diretta del metodo sia la sua 
implementazione; in caso contrario, durante la generazione del progetto, si otterra un 
errore del compilatore. 
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Componenti multipiattaforma e non multipiattaforma 



La Component palette contiene una selezione di componenti in grado di gestire 
un'ampia gamma di operazioni di programmazione. I componenti sono disposti in 
diverse pagine in base al loro scopo e alle funzionalita. Per esempio, i componenti 
usati piu frequentemente, come quelli per creare i menu, le caselle di modifica o i 
pulsanti, si trovano nella pagina Standard. Le pagine visualizzate nella 
configurazione predefinita dipendono dalla versione del prodotto che si possiede. 

La Tabella 3.3 elenca le tipiche pagine predefinite e i componenti disponibili per la 
creazione di applicazioni, comprese quelle che non sono portabili su altre 
piattaforme. E possibile utilizzare tutti i componenti CLX sia in applicazioni 
Windows che Linux. E possibile utilizzare alcuni componenti specifici della VCL in 
applicazioni CLX solo per Windows, tuttavia, in tal caso, le applicazioni non saranno 
portabili su altre piattaforme a meno che non si isolino queste parti del codice. 

Tabella 5.1 Pagine della Component palette 
Nome della 

pagina Descrizione Multipiattaforma? 

Standard Controlli standard, menu Si 

Additional Controlli specializzati Si, tranne ApplicationEvents, Action- 



(Win32 (VCL) / Controlli comuni di Windows 
Controlli comuni 



(CLX) 



Manager, ActionMainMenuBar, 
ActionToolBar, e CustomizeDlg. 
LCDNumber e solo nella CLX. 

La maggior parte dei componenti 
presenti sulla pagina Win32 sono 
anche sulla pagina Common Con- 
trols che viene visualizzata quando si 
crea un'applicazione CLX. 

RichEdit, UpDown, HotKey, Ani- 
mate, DataTimePicker, MonthCalen- 
dar, Coolbar, PageScroller e 
ComboBoxEx si trovano solo nella 
VCL. 

TextBrowser, TextViewer, Icon- 
Viewer e SpinEdit sono solo nella 



System 



Componenti e controlli per accesso a 
livello di sistema, inclusi timer, multime- 
dia e DDE. 



CLX. 

No, tranne Timer e PaintBox, che 
sono presenti sulla pagina Additio- 
nal quando si crea un'applicazione 



Data Access 



Componenti per operazioni con dati di 
database che non sono legati a nessun 
particolare meccanismo di accesso ai 
dati. 



CLX. 

Si, tranne XMLTransform, XMLTran- 
sformProvider e XMLTransfor- 
mClient. 



Data Controls 



Controlli visuali data-aware. 



Si, tranne DBRichEdit, DBCtrlGrid e 
DBChart. 
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Tabella 5.1 Pagine della Component palette (continua) 
Nome della 

pagina Descrizione 

dbExpress Controlli di database che utilizzano 

dbExpress, uno strato multipiattaforma, 
indipendenet dal database, che fornisce 
metodi per l'elaborazione SQL dinamica. 
Definisce un'interfaccia comune per 
l'accesso a server SQL. 

DataSnap Componenti utilizzati per la creazione di 

applicazioni database multi-tiered. 

BDE Componenti che forniscono l'accesso di 

dati tramite Borland Database Engine. 

ADO Componenti che forniscono l'accesso ai 

dati tramite il framework ADO. 

InterBase Componenti che forniscono accesso 

diretto a InterBase. 

InterBaseAdmin Componenti che accedono alle chiamate 
API degli InterBase Services. 

InternetExpress Componenti che sono contemporanea- 
mente un'applicazione Web server e 
client di un'applicazione database multi- 
tiered. 

Internet Componenti per protocolli di comunica- 

zione Internet e per applicazioni Web. 

WebSnap Componenti per la creazione di applica- 

zioni per Web server. 

FastNet Controlli Internet NetMasters. 

QReport Componenti QuickReport per la crea- 

zione di report interni. 

Dialogs Finestre di dialogo di uso comune. 



Win 3.1 Componenti in stile Win 3.1. 

Samples Componenti custom di esempio. 

ActiveX Controlli ActiveX di esempio; consultare 

la documentazione Microsoft 
(msdn.microsoft.com). 

COM+ Componente per la gestione di eventi 

COM+. 

WebServices Componenti per la scrittura di applica- 
zioni che implementano o utilizzano ser- 
vizi Web basati su SOAP. 

Servers Esempi di server COM per Microsoft 

Excel, Word e cosi via (consultare la 
documentazione MSDN di Microsoft). 

Indy Clients Componenti Internet multipiattaforma 

per il client (componenti Internet Win- 
shoes open-source). 



Multipiattaf 



rma? 



Si 



No 

No 

No 

Si 

Si 

No 

No 

No 

No 
No 

Si, tranne OpenPictureDialog, Save- 
PictureDialog, PrinterDialog e Prin- 
terSetupDialog. 

No 

No 

No 

No 
No 

No 

Si 
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Tabella 5.1 Pagine della Component palette (continua) 



Nome della 
pagina 


Descrizione 


Multipiattaforma? 


Indy Servers 


Componenti Internet multipiattaforma 
per il server (componenti Internet Win- 
shoes open-source). 


Si 


Indy Misc 


Componenti Internet multipiattaforma 
aggiuntivi (componenti Internet Win- 
shoes open-source). 


Si 



E possibile aggiungere, rimuovere e riordinare i componenti sulla tavolozza, o creare 
modelli di componenti e frame per raggruppare piu componenti. 

La Guida in linea contiene informazioni sui componenti inclusi nella Component 
palette. Alcuni componenti presenti nelle pagine ActiveX, Server e Samples, tuttavia, 
sono forniti solamente a titolo di esempio e non sono documentati. 

Per ulteriori informazioni sulle differenze fra la VCL e la CLX, vedere il Capitolo 14, 
"Sviluppo di applicazioni multipiattaforma". 

Aggiunta di componenti custom alia Component palette 

E possibile installare nella Component palette componenti custom-scritti 
personalmente o da terze parti- e utilizzarli nelle proprie applicazioni. Per scrivere 
un componente personalizzato, vedere la Parte V, "Creazione di componenti 
custom". Per installare un componente esistente, consultare la sezione "Installazione 
di package di componenti" a pagina 15-6. 
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Capitolo 




Uso dei controlli 



I controlli sono componenti visuali con cui l'utente pud interagire in fase di 
esecuzione. Questo capitolo descrive le varie caratteristiche comuni alia maggior 
parte dei controlli. 

Implementazione del drag and drop nei controlli 



La funzionalita drag-and-drop (trascinamento e rilascio) degli elementi e spesso 
molto utle agli utenti nella manipolazione degli oggetti. Si puo fare in modo che un 
utente sia libero di trascinare un intero controllo, o gli elementi contenuti in un 
controllo — ad esempio un controllo casella di riepilogo o una vista ad albero — in un 
altro. 

• Inizio di un'operazione di trascinamento 

• Accettazione degli elementi rilasciati 

• Rilascio di elementi 

• Fine di un'operazione di trascinamento 

• Personalizzazione delle operazioni di drag-and-drop con un oggetto drag 

• Modifica del puntatore di trascinamento del mouse 

Inizio di un'operazione di trascinamento 



Ogni controllo ha una proprieta di nome DragMode che determina come vengono 
iniziate le operazioni di trascinamento. Se DragMode e dmAutomatic, il trascinamento 
inizia automaticamente quando l'utente preme un pulsante del mouse con il cursore 
sul controllo. Dal momento che dmAutomatic puo interferire con la normale attivita 
del mouse, e opportuno impostare DragMode a dmManual (impostazione predefinita) 
e iniziare il trascinamento per gestire gli eventi mouse-down. 

Per iniziare a trascinare manualmente un controllo, occorre chiamare il suo metodo 
BeginDrag. BeginDrag accetta un parametro booleano di nome Immediate e un 
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parametro integer di nome Threshold. Se si passa true per Immediate, il trascinamento 
inizia immediatamente. Se si passa false, il trascinamento non inizia finche l'utente 
non sposta il mouse del numero di pixel specificati da Threshold. Se il valore di 
Threshold e -1, viene utilizzato un valore predefinito. La chiamata 

BeginDrag (false, -1) ; 

consente al controllo di accettare i clic del mouse senza iniziare un'operazione di 
trascinamento. 

Verificando i parametri dell'evento mouse-down prima di chiamare BeginDrag, e 
possibile porre altre condizioni su quando iniziare il trascinamento, come il controllo 
del pulsante che ha premuto l'utente. II codice seguente, per esempio, gestisce un 
evento mouse-down in una casella di riepilogo di file iniziando il trascinamento solo 
se e stato premuto il pulsante sinistro del mouse. 

void __fastcall TFMForm: : FileListBoxlMouseDown (TObj ect *Sender, 
TMouseButton Button, TShiftState Shift, int X, int Y) 

{ 

if (Button == mbLeft)// drag only if left button pressed 
{ 

TFileListBox *pLB = (TFileListBox *) Sender; // cast to TFileListBox 
if (pLB->ltemAtPos (Point (X,Y) , true) >= 0) // is there an item here? 
pLB->BegmDrag(false, -1); // if so, drag it 

} 

} 

Accettazione degli elementi rilasciati 



Quando l'utente trascina qualcosa su un controllo, questo riceve un evento 
OnDragOver, e in quel momento deve indicare se pud accettare l'elemento nel caso in 
cui l'utente dovesse rilasciarlo. II cursore di trascinamento si trasforma per indicare 
se il controllo puo accettare o meno l'elemento trascinato. Per accettare gli elementi 
trascinati su un controllo, occorre collegare il gestore all'evento OnDragOver del 
controllo. 

L'evento drag-over ha un parametro di nome Accept che il gestore di evento puo 
impostare a true se accettera l'elemento. Accept puo modificare o meno il tipo di 
cursore in un cursore di accettazione. 

L'evento drag-over possiede altri parametri, compresa la sorgente del trascinamento 
e la posizione corrente del cursore del mouse, che il gestore di evento puo usare per 
determinare se accettare o meno il rilascio. Nell'esempio seguente una vista 
dell'albero della directory accetta gli elementi trascinati soltanto se provengono da 
una casella di riepilogo di file. 

void fastcall TForml: :TreeViewlDragOver( TObj ect *Sender, TObject *Source, 

int X, int Y, TDragState State, bool &Accept) 

{ 

if (Source->InheritsFrom(__classid (TFileListBox) ) ) 
Accept = true; 

} 
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Rilascio di elementi 



Se un controllo indica che puo accettare un elemento trascinato, e necessario gestire 
l'elemento che viene rilasciato su di esso. Per gestire gli elementi rilasciati, si deve 
collegare un gestore all'evento OnDragDrop del controllo che accetta l'elemento 
rilasciato. Come l'evento drag-over, l'evento drag-and-drop indica la sorgente 
dell'elemento trascinato e le coordinate del cursore del mouse sul controllo 
accettante. L'ultimo parametro consente di monitorare il percorso compiuto da un 
oggetto durante il trascinamento; ad esempio, si potrebbe utilizzare questa 
informazione per modificare il colore dei componenti, man mano che l'oggetto passa 
sopra di essi. 

Nell'esempio che segue, una vista ad albero della directory,che accetta elementi 
trascinati da una casella di riepilogo di file, risponde spostando i file nella directory 
su cui questi vengono rilasciati. 

void __fastcall TForml: :TreeViewlDragDrop (TObject *Sender, TObject *Source, 
int X, int Y) { 

if (Source->InheritsFroro(__classid (TFileListBox) ) ) 

{ 

TTreeNode *pNode = TreeViewl->GetNodeAt (X, Y) ; // pNode is drop target 
AnsiString NewFile = pNode->Text + AnsiString ( "// " ) + 

ExtractFileName (FileListBoxl->FileName) ; // build file name for drop target 
MoveFileEx (FileListBoxl->FileName.c_str ( ) , NewFile . c_str ( ) , 

MOVEFILE_REPLACE_EXISTING I M0VEFILE_C0PY_ ALLOWED) ; // move the file 

} 

} 

Fine di un'operazione di trascinamento 



Un'operazione di trascinamento termina o quando l'elemento viene rilasciato con 
successo oppure quando viene rilasciato su un controllo che non e in grado di 
accettarlo. A questo punto, al controllo da cui l'elemento e stato trascinato, viene 
inviato un evento end-drag. Affinche un controllo possa rispondere quando gli si 
prelevano degli elementi, occorre associare all'evento OnEndDrag del controllo un 
gestore di evento. 

II parametro piu importante di un evento OnEndDrag e chiamato Target, per indicare 
qual e il controllo eventuale che accetta il rilascio. Se Target e null, significa che 
nessun controllo accetta l'elemento trascinato. L'evento OnEndDrag include le 
coordinate sul controllo ricevente. 

In questo esempio, una casella di riepilogo di file gestisce un evento end-drag 
effettuando l'aggiornamento del suo elenco di file. 

void __fastcall TFMForm: :FileListBoxlEndDrag (TObject *Sender, TObject *Target, int X, int 

Y) 

if (Target) 
FileListBoxl->Update() ; 

}; 
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Personalizzazione delle operazioni di drag-and-drop con un oggetto 
drag 



Per personalizzare il comportamento drag-and-drop dell 'oggetto e possibile usare un 
discendente di TDragObject. Per impostazione predefinita, gli eventi drag-over e 
drag-and-drop indicano la sorgente dell'elemento trascinato e le coordinate del 
cursore del mouse sul controllo accettante. Per ottenere altre informazioni dello stato, 
derivare da TDragObject o da TDragObjectEx(solo per VCL) un oggetto drag custom e 
ridefinirne i metodi virtuali. Creare l'oggetto drag custom nell'evento OnStartDrag. 

Di solito, il parametro sorgente degli eventi drag-over e drag-and-drop e il controllo 
che inizia l'operazione di trascinamento. Se un'operazione che coinvolge gli stessi 
tipi di dati puo essere iniziata da tipi di controllo differenti, il sorgente deve 
supportare ciascun tipo di controllo. Comunque, se si utilizza un discendente di 
TDragObject, il sorgente e lo stesso oggetto drag; se ogni controllo crea lo stesso tipo 
di oggetto drag nel proprio evento OnStartDrag, il controllo di destinazione deve 
essere in grado di gestire un solo tipo di oggetto. Gli eventi drag-over e drag-and- 
drop possono riferire se il sorgente e un oggetto drag, invece del controllo, 
chiamando la funzione IsDragObject. 

I discendenti di TDragObjectEx (solo per VCL) vengono liberati automaticamente al 
contrario dei discendenti di TDragObject. Se si hanno discendenti di TDragObject che 
non vengono liberati esplicitamente, e possibile modificarli in modo che discendano 
invece da TDragObjectEx in modo da evitare perdite di memoria. 

Gli oggetti drag consentono di trascinare elementi fra una scheda implementata nel 
file EXE principale dell'applicazione e una scheda implementata utilizzando una 
DLL, o fra schede implementate utilizzando DLL differenti. 

Modifica del puntatore di trascinamento del mouse 



Impostando la proprieta DragCursor del componente sorgente e possibile 
personalizzare l'aspetto del puntatore del mouse durante le operazioni di 
trascinamento). 

Implementazione del drag-and-dock nei controlli 



I discendenti di TWinControl possono agire come posizioni di aggancio e i 
discendenti di TControl possono, invece, comportarsi come finestre figlio che 
vengono agganciate alle posizioni specificate. Per esempio, per fornire una posizione 
di aggancio al margine sinistra di una finestra scheda, si deve allineare un riquadro 
al margine sinistra della scheda e renderlo una posizione di aggancio. Quando i 
controlli agganciabili vengono trascinati nel riquadro e vengono rilasciati, diventano 
controlli figlio del riquadro. 

• Trasformazione di un controllo con finestra in una posizione di aggancio 

• Trasformazione di un controllo in un figlio agganciabile 

• Controllo della modalita di aggancio dei controlli figlio 
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• Controllo della modalita di sgancio dei controlli figlio 

• Controllo della modalita di risposta dei controlli figlio alle operazioni drag-and- 
dock 

Le proprieta drag-and-dock sono disponibili nella VCL ma non in CLX. 

Trasformazione di un controllo con finestra in una posizione di 
aggancio 

Per rendere un controllo finestra una posizione di aggancio: 

1 Impostare la proprieta DockSite a true. 

2 Se l'oggetto della posizione di aggancio non deve apparire se non contiene un 
client agganciato, impostare la sua proprieta AutoSize a true. Quando AutoSize e 
true, la posizione di aggancio ha come dimensione finche non accetta un 
controllo figlio per l'aggancio. Quindi, viene ridimensionata in modo tra trovare 
posto intorno al controllo figlio. 

Trasformazione di un controllo in un figlio agganciabile 



Per trasformare un controllo in un figlio agganciabile: 

1 Impostare la sua proprieta DragKind a dkDock. Quando DragKind e dkDock, il 
trascinamento del controllo lo sposta in una nuova posizione di aggancio o sgancia 
il controllo in modo che diventi una finestra mobile. Quando DragKind e dkDrag 
(impostazione predefinita), il trascinamento del controllo avvia un'operazione 
drag-and-drop che deve essere implementata usando gli eventi OnDragOver, 
OnEndDrag e OnDragDrop. 

2 Impostare la sua proprieta DragMode a dm Automatic. Quando DragMode e 
dmAutomatic, il trascinamento (per l'operazione drag-and-drop o di aggancio, in 
funzione di DragKind) viene iniziato automaticamente quando l'utente avvia il 
trascinamento del controllo con il mouse. Quando DragMode e dmManual, e ancora 
possibile iniziare un'operazione drag-and-dock (o drag-and-drop) chiamando il 
metodo BeginDrag. 

3 Impostare la sua proprieta FloatingDockSiteClass per indicare il discendente 
TWinControl che ospitera il controllo quando sara sganciato e lasciato come 
finestra mobile. Quando il controllo viene rilasciato in una posizione diversa da 
quella di aggancio, viene creato dinamicamente un controllo finestra di questa 
classe, che diventa il genitore del figlio agganciabile. Se il controllo del figlio 
agganciabile e un discendente di TWinControl, non e necessario creare una distinta 
posizione di aggancio mobile per ospitare il controllo, anche se puo essere 
opportuno specificare una scheda per ottenere un bordo e una barra del titolo. Per 
omettere una finestra contenitore dinamica, si deve impostare 
FloatingDockSiteClass alia stessa classe del controllo; in questo modo diventera una 
finestra mobile senza alcun genitore. 
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Controllo della modalita di aggancio dei controlli figlio 



Un posizione di aggancio accetta automaticamente i controlli figlio quando vi 
vengono rilasciati sopra. Per la maggior parte dei controlli il primo figlio viene 
agganciato per riempire l'area client, il secondo la divide in due regioni distinte, e 
cosi via. I controlli pagina agganciano i figli in nuovi fogli di tabulazione (o fondono i 
fogli di tabulazione se il figlio e un altro controllo pagina). 

Tre eventi consentono alle posizioni di aggancio di limitare ulteriormente il modo in 
cui vengono agganciati i controlli figlio: 

__property TGetSitelnfoEvent OnGetSitelnfo = {read=FOnGetSiteInfo, write=FOnGetSiteInfo} ; 
typedef void __fastcall (__closure *TGetSiteInfoEvent) (System: :T0bject* Sender, TControl* 
DockClient, Windows : :TRect &Inf luenceRect , const Windows : :TPoint &MousePos, bool &CanDock) ; 

OnGetSitelnfo si verifica nella posizione di aggancio quando l'utente trascina un figlio 
agganciabile sul controllo. Questo evento consente alia posizione di indicare se 
accettera o meno il controllo specificato dal parametro DockClient come figlio, e in 
caso di risposta positiva, dove deve essere agganciato il figlio. Quando si verifica 
OnGetSitelnfo, InfluenceRect viene inizializzato alle coordinate dello schermo della 
posizione di aggancio, e CanDock viene inizializzato a true. Modificando 
InfluenceRect, puo essere creata una regione di aggancio piu limitata, mentre il figlio 
puo essere rifiutato impostando CanDock a false. 

property TDockOverEvent OnDockOver = {read=FOnDockOver, write =FOnDockOver } ; 

typedef void __fastcall (__closure *TDockOverEvent) (System: :T0bject* Sender, 
TDragDockObject* Source, int X, int Y, TDragState State, bool &Accept); 

OnDockOver si verifica nella posizione di aggancio quando l'utente trascina sul 
controllo un figlio agganciabile. Corrisponde all'evento OnDragOver in una normale 
operazione drag-and-drop. Deve essere utilizzato per segnalare che il figlio puo 
essere rilasciato dalla posizione di aggancio, impostando il parametro Accept. Se il 
controllo agganciabile e stato rifiutato dal gestore di evento OnGetSitelnfo (forse 
perche il tipo di controllo era errato), l'evento OnDockOver non verra attivato. 

property TDockDropEvent OnDockDrop = {read=FOnDockDrop, write=FOnDockDrop} ; 

typedef void __fastcall (__closure *TDockDropEvent) (System: :T0bject* Sender, 
TDragDockObject* Source, int X, int Y) ; 

OnDockDrop si verifica nella posizione di aggancio quando l'utente rilascia un figlio 
agganciabile sul controllo. Corrisponde all'evento OnDragDrop in una normale 
operazione drag-and-drop. Deve essere utilizzato per eseguire un adattamento 
necessario per accettare il controllo come controllo figlio. I/accesso al controllo figlio 
puo essere ottenuto usando la proprieta Control del TDockObject specificato dal 
parametro Source. 

Controllo della modalita di sgancio dei controlli figlio 



Una posizione di controllo consente automaticamente ai controlli figlio di essere 
sganciati quando vengono trascinati ed hanno la proprieta DragMode impostata a 
dm Automatic. Le posizioni di aggancio possono rispondere quando i controlli figlio 
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vengono trascinati fuori, e possono anche impedire lo sganciamento in un gestore di 
evento OnUnDock: 

__property TUnDockEvent OnUnDock = {read=FOnUnDock, write=FOnUnDock} ; 

typedef void __fastcall (__closure *TUnDockEvent ) (System: :T0bject* Sender, TControl* 

Client, TWinControl* NewTarget, bool SAllow) ; 

II parametro Client indica il controllo figlio che sta tentando lo sganciamento, mentre 
il parametro Allow consente alia posizione di aggancio (Sender) di rifiutare lo 
sganciamento. Quando si implementa un gestore di evento OnUnDock, puo risultare 
utile conoscere quali altri figli (eventuali) sono al momento agganciati. Queste 
informazioni sono disponibili nella proprieta a sola lettura DockClients, che e un array 
indicizzato di TControl. II numero di client agganciati viene indicato dalla proprieta a 
sola lettura DockClientCount. 

Controllo della modalita di risposta dei controlli figlio alle operazioni 
drag-and-dock 



I controlli figlio agganciabili hanno due eventi che si verificano durante le operazioni 
drag-and-dock: OnStartDock, analogo all'evento OnStartDrag di un'operazione drag- 
and-drop, consente al controllo figlio agganciabile di creare un oggetto 
trascinamento personalizzato. OnEndDock, analogamente all'evento OnEndDrag, si 
verifica al termine del trascinamento. 

Operazioni con testo nei controlli 



Le sezioni seguenti spiegano come utilizzare le varie funzioni dei controlli RichEdit e 
Memo. Alcune funzioni qui descritte valgono anche per i controlli di editing. 

• Impostazione dell'allineamento del testo 

• Aggiunta di barre di scorrimento in fase di esecuzione 

• Aggiunta dell'oggetto clipboard 

• Selezione di testo 

• Selezione di tutto il testo 

• Operazioni taglia, copia e incolla del testo 

• Cancellazione del testo selezionato 

• Disattivazione delle voci di menu 

• Preparazione di un menu a comparsa 

• Gestione dell'evento OnPopup 

Impostazione dell'allineamento del testo 



In un componente RichEdit o Memo, il testo puo essere allineato a sinistra, a destra o 
al centre Per cambiare l'allineamento del testo, impostare la proprieta Alignment del 
componente di editing. L'allineamento ha effetto solo se la proprieta Wordwrap e 
true; se l'allineamento alia riga successiva e disattivato, non esiste alcun margine 
rispetto al quale effettuare l'allineamento. 
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Ad esempio, il codice seguente tratto dall'esempio RichEdit imposta l'allineamento a 
seconda del pulsante scelto: 

switch ( (int)RichEditl->Paragraph->Alignment) 

{ 

case 0: LeftAlign->Down = true; break; 
case 1: RightAlign->Down = true; break; 
case 2: CenterAlign->Down = true; break; 

} 



Aggiunta di barre di scorrimento in fase di esecuzione 

I componenti RichEdit e Memo possono contenere barre di scorrimento orizzontali o 
verticali, o entrambe, a seconda delle necessita. Quando l'allineamento alia riga 
successiva e attivato, il componente ha bisogno solo di una barra di scorrimento 
verticale. Se l'utente disattiva l'allineamento alia riga successiva, il componente pud 
richiedere anche una barra di scorrimento orizzontale, poiche il testo non e 
delimitato dal lato destro dell'editor. 

Aggiunta di barre di scorrimento in fase di esecuzione: 

1 Determinare se il testo puo superare o meno il margine destro. In molti casi, cio 
significa controllare se la funzionalita di a capo automatico e abilitata. Si puo 
anche controllare se qualche riga di testo supera la larghezza del controllo. 

2 Impostare la proprieta ScrollBars del componente RichEdit o Memo per includere 
o escludere le barre di scorrimento. 

L'esempio seguente collega un gestore di evento OnClick alia voce di menu 
Character I Word Wrap. 

void __fastcall TEditForm: :WordWraplClick(TObject *Sender) 

{ 

Editor->WordWrap = ! (Editor->WordWrap) ; // toggle word wrapping 
if (Editor->WordWrap) 

Editor->ScrollBars = ssVertical; // wrapped requires only vertical 

else 

Editor->ScrollBars = ssBoth; // unwrapped can need both 

WordWrapl->Checked = Editor->WordWrap; // check menu item to match property 

} 

I componenti RichEdit e Memo gestiscono le loro barre di scorrimento in modo 
leggermente diverse II componente RichEdit puo nascondere le sue barre di 
scorrimento se il testo sta all'interno dei suoi margini. II componente Memo mostra 
sempre le barre di scorrimento se sono attivate. 



Aggiunta dell'oggetto clipboard 



La maggior parte delle applicazioni di gestione del testo fornisce agli utenti un modo 
per spostare il testo selezionato tra i documenti, compresi quelli di applicazioni 
differenti. L'oggetto Clipboard in C++Builder incapsula una clipboard (come la 
clipboard di Windows) e include i metodi per tagliare, copiare e incollare il testo (e 
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altri formati, compresi i grafici). L'oggetto Clipboard viene dichiarato nella unit 
Clipbrd. 

Aggiunta dell'oggetto Clipboard ad un'applicazione: 

1 Selezionare la unit che usera la clipboard. 

2 Nel file .h della scheda, aggiungere 

♦include <vcl\Clipbrd.hpp> 

Selezione del testo 



Prima di poterlo inviare nella clipboard, il testo desiderato deve essere selezionato. 
L'evidenziazione del testo selezionato e incorporata nei componenti Edit. Quando 
l'utente seleziona il testo, esso appare evidenziato. 

La Tabella 6.1 elenca le proprieta usate comunemente per gestire il testo selezionato. 



Tabella 6.1 Proprieta del testo selezionato 



Proprieta 


Descrizione 


SelText 


Contiene una stringa che rappresenta il testo selezionato nel 




componente. 


SelLength 


Contiene la lunghezza di una stringa selezionata. 


SelStart 


Contiene la posizione iniziale di una stringa relativa all'inizio di un 




buffer di testo di un controllo edit. 



Selezione di tutto il testo 



II metodo SelectAll seleziona tutto il contenuto di un controllo di editing, come ad 
esempio, un componente rich edit o memo. Cio e particolarmente utile quando il 
contenuto del componente supera l'area visibile del componente. In molti altri casi 
gli utenti selezionano il testo con le combinazioni di tasti o con il trascinamento del 
mouse. 

Per selezionare l'intero contenuto di un controllo RichEdit o Memo, si deve chiamare 
il metodo SelectAll del controllo RichEditl. 

Ad esempio: 

void __fastcall TMainForm: : SelectAll (TObject *Sender) 
{ 

RichEditl->SelectAll() ; // select all text in RichEdit 

) 

Operazione taglia, copia e incolla del testo 



Le applicazioni che usano la unit Clipbrd possono tagliare, copiare e incollare testo, 
grafici e oggetti tramite la clipboard. Tutti i componenti Edit che incapsulano i 
controlli standard di Windows per la gestione del testo hanno metodi incorporati per 
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interagire con la clipboard. (Per informazioni sull'uso della clipboard con i grafici, 
consultare il paragrafo "Uso della clipboard con i grafici" a pagina 10-22.) 

Per tagliare, copiare o incollare testo tramite la clipboard, si devono chiamare, 
rispettivamente, i metodi CutToClipboard, CopyToClipboard, e PasteFromClipboard del 
componente Edit. 

Per esempio, il codice seguente collega i gestori agli eventi OnClick, rispettivamente 
dei comandi Edit I Cut, Edit I Copy e Edit I Paste: 

void __fastcall TMainForm: :EditCutClick(TObject* Sender) 
{ RichEditl->CutToClipboard() ; 

void __fastcall TMainForm: :EditCopyClick(TObject* Sender) 
{ RichEditl->CopyToClipboard() ; 

void __fastcall TMainForm: :EditPasteClick(TObject* Sender) 
{ RichEditl->PasteFromClipboard() ; 



Cancellazione del testo selezionato 



E possibile cancellare il testo selezionato in un componente Edit senza tagliarlo e 
collocarlo nella clipboard. Per fare cio, chiamare il metodo ClearSelection. Ad 
esempio, se nel menu Edit c'e un elemento Delete, il codice potrebbe assomigliare al 
seguente: 

void __fastcall TMainForm: :EditDeleteClick(TObject *Sender) 
{ 

RichEditl->ClearSelection ( ) ; 

} 

Disattivazione delle voci di menu 



E spesso utile disattivare i comandi di menu senza rimuoverli dal menu. Per 
esempio, in un editor di testi, se al momento non c'e alcun testo selezionato, non e 
possibile utilizzare i comandi Cut, Copy e Delete. L'attivazione o la disattivazione 
delle voci di menu puo essere compiuta, ad esempio, nel momento in cui l'utente 
seleziona il menu. Per disattivare una voce di menu, impostarne la proprieta Enabled 
a false. 

Nell' esempio seguente, un gestore viene collegato all'evento OnClick della voce Edit 
in una barra di menu della scheda figlio. Questo gestore imposta la proprieta Enabled 
delle voci Cut, Copy e Delete del menu Edit a seconda che in RichEditl vi sia o meno 
del testo selezionato. II comando Paste viene attivato o disattivato in base al fatto che 
esista o meno un testo nella clipboard. 

void __fastcall TMainForm: :EditEditClick(TObject *Sender) 
{ 

// enable or disable the Paste menu item 
Pastel->Enabled = Clipboard ( ) ->HasFormat (CF_TEXT) ; 

bool HasSelection = (RichEditl->SelLength > 0); // true if text is selected 
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Cutl->Enabled = HasSelection; // enable menu items if HasSelection is true 
Copyl->Enabled = HasSelection; 
Deletel->Enabled = HasSelection; 

} 

II metodo HasFormat della clipboard restituisce un valore booleano a seconda che la 
clipboard contenga o meno oggetti, testo o immagini di un particolare formato. 
Chiamando HasFormat con il parametro CF_TEXT, si puo determinare se la clipboard 
contenga o meno un testo, e attivare o disattivare la voce Paste. 

II Capitolo 10, "Operazioni con elementi grafici e multimediali" fornisce ulteriori 
informazioni sull'utilizzo della clipboard con i grafici. 

Preparazione di un menu a comparsa 



I menu a comparsa, o locali, sono una caratteristica comune facile da usare per 
qualsiasi applicazione. Essi consentono agli utenti di ridurre al minimo lo 
spostamento del mouse facendo clic sul pulsante destro nello spazio di lavoro 
dell'applicazione per accedere ad un elenco di comandi di uso frequente. 

In un' applicazione text editor, per esempio, si puo aggiungere un menu a comparsa 
che ripeta i comandi di editing Cut, Copy e Paste. Queste voci del menu a comparsa 
possono usare gli stessi gestori di evento delle corrispondenti voci del menu Edit. 
Non occorre creare combinazioni di tasti o tasti di scelta rapida per i menu a 
comparsa, perche le voci corrispondenti del menu corrispondenti generalmente 
hanno gia dei tasti di scelta rapida. 

La proprieta PopupMenu di una scheda specifica quale menu a comparsa visualizzare 
quando un utente fa clic con il tasto destro su un elemento della scheda. I singoli 
controlli hanno anche proprieta PopupMenu che possono ridefinire la proprieta della 
scheda, consentendo l'uso di menu personalizzati per particolari controlli. 

Per aggiungere un menu a comparsa a una scheda: 

1 Collocare un componente PopupMenu sulla scheda. 

2 Usare il Menu Designer per definire le voci del menu a comparsa. 

3 Impostare la proprieta PopupMenu della scheda o del controllo che visualizza il 
menu al nome del componente menu a comparsa. 

4 Collegare i gestori agli eventi OnClick delle voci del menu a comparsa. 

Gestione dell'evento OnPopup 



Puo essere opportuno regolare le voci del menu a comparsa prima di visualizzare il 
menu, proprio come avviene per l'attivazione o disattivazione delle voci di un 
normale menu. Con un menu normale e possibile gestire l'evento OnClick per la voce 
posta all'inizio del menu, come descritto nel paragrafo "Disattivazione delle voci di 
menu" a pagina 6-10. 

Con un menu a comparsa, invece, non c'e alcuna barra di menu al livello piu alto, 
quindi per preparare i comandi del menu a comparsa occorre gestire l'evento nel 
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componente menu stesso. II componente menu a comparsa fornisce un evento, 
chiamato, solo per questo scopo, OnPopup. 

Per regolare le voci su un menu a comparsa prima di visualizzarle: 

1 Selezionare il componente menu a comparsa. 

2 Collegare un gestore al suo evento OnPopup. 

3 Scrivere il codice nel gestore di evento per attivare, disattivare, nascondere o 
mostrare le voci del menu. 

Nel seguente codice il gestore di evento EditlClick, descritto precedentemente in 
"Disattivazione delle voci di menu" a pagina 6-10 viene collegato all'evento OnPopup 
del componente menu a comparsa. A EditlClick viene aggiunta una riga di codice per 
ciascuna voce del menu popup. 

void __fastcall TMainForm: :EditEditClick(TObject *Sender) 
{ 

// enable or disable the Paste menu item 

Pastel->Enabled = Clipboard ( ) ->HasFormat (CF_TEXT) ; 

Paste2->Enabled = Pastel->Enabled; // add this line 

bool HasSelection = (RichEditl->SelLength > 0); // true if text is selected 

Cutl->Enabled = HasSelection; // enable menu items if HasSelection is true 

Cut2->Enabled = HasSelection; // add this line 

Copyl->Enabled = HasSelection; 

Copy2->Enabled = HasSelection; // add this line 

Deletel->Enabled = HasSelection; 

} 

Aggiunta di grafici ai controlli 



Diversi controlli consentono di personalizzare il modo in cui il controllo viene 
rappresentato. Questi controlli includono caselle di riepilogo, caselle combinate, 
menu, headers, controlli multipagina, viste a elenco, barre di stato, viste ad albero e 
barre strumenti. Fra questi vi sono caselle di riepilogo, caselle combinate, menu, 
intestazioni, controlli pagina, viste elenco, barre di stato, viste ad albero e barre 
strumenti. L'uso piu comune dei controlli owner-draw consiste nel fornire grafici in 
sostituzione o in aggiunta al testo per gli elementi. Per informazioni su come usare lo 
stile owner-draw per aggiungere immagini ai menu, consultare "Aggiunta di 
immagini alle voci di menu" a pagina 8-38. 

Tutti i controlli owner-draw contengono elenchi di elementi. Di solito, quelle liste 
sono liste di stringhe che vengono visualizzate come testo, oppure liste di oggetti che 
contengono stringhe che vengono visualizzate come testo. E possibile associare un 
oggetto a ciascun elemento di un elenco per facilitarne l'uso quando si disegnano gli 
elementi. 

In generale, la creazione di un controllo owner-draw in C++Builder implica la 
conoscenza dei seguenti argomenti: 

1 Come indicare che un controllo e owner-drawn. 

2 Aggiunta di oggetti grafici ad un elenco di stringhe. 

3 Disegno di elementi owner-draw 
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Come indicare che un controllo e owner-drawn 



Per personalizzare il tracciamento di un controllo, e necessario approntare dei gestori 
di evento che siano in grado di tracciare all'occorrenza l'immagine del 
controllo. Alcuni controlli ricevono questi eventi in modo automatico. Ad esempio, 
viste elenco, viste ad albero e barre strumenti ricevono tutti eventi a diversi stadi 
durante il processo di tracciamento, senza dover impostare alcuna proprieta. Questi 
eventi hanno nomi come "OnCustomDraw" oppure "OnAdvancedCustomDraw". 

Altri controlli, tuttavia, necessitano che l'impostazione una proprieta prima che 
possano ricevare eventi owner-draw. Le caselle di riepilogo, le caselle combinate, i 
controlli header e le barre di stato hanno una proprieta di nome Style. Style determina 
se il controllo utilizza o meno il disegno predefinito (chiamato stile "standard") o il 
disegno personalizzato. Le griglie utilizzano una proprieta di nome DefaultDrawing 
per attivare o disattivare il disegno predefinito. Le viste ad elenco e i controlli 
multipagina hanno una proprieta di nome OwnerDraw che attiva o disattiva il 
disegno predefinito. 

Le caselle di riepilogo e le caselle combinate hanno stili owner-draw aggiuntivi, 
chiamati/zxed e variable, come descritto nella Tabella 6.2. Altri controlli sempre sono 
fixed e, sebbene la dimensione deU'elemento che contiene il testo pud variare, la 
dimensione di ciascuno elemento viene determinata prima di disegnare il controllo. 

Tabella 6.2 Confronto dello stile owner-draw fixed con quello variable 
Stile owner-draw Significato Esempi 

Fixed Ogni elemento ha la stessa altezza, e IbOwnerDrawFixed, 

precisamente quella determinata dalla csOwnerDrawFixed 
proprieta ItemHeight. 

Variable Ogni elemento puo avere un'altezza diversa, IbOwnerDraivVariable, 

determinata dai dati forniti al momento csOwnerDrawVariable 
dell'esecuzione. 



Aggiunta di oggetti grafici ad un elenco di stringhe 



Ogni elenco di stringhe ha la possibility di contenere un elenco di oggetti, in aggiunta 
al suo elenco di stringhe. 

Per esempio, in un'applicazione file manager, puo essere opportuno aggiungere le 
bitmap che indicano il tipo di unita insieme alia relativa lettera. A questo scopo, 
occorre aggiungere le immagini bitmap all'applicazione, quindi copiarle nei posti 
corretti dell'elenco di stringhe, come descritto nelle sezioni seguenti. 

Aggiunta di immagini ad un'applicazione 

Un controllo Image e un controllo non visuale che contiene un'immagine grafica, 
come una bitmap. I controlli immagine vengono usati per visualizzare immagini 
grafiche su una scheda. Inoltre, possono essere usati per contenere immagini 
nascoste che verranno usate nell'applicazione. Per esempio, si possono memorizzare 
bitmap per controlli owner-draw in controlli Image nascosti nel modo seguente: 
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1 Aggiungere i controlli immagine alia scheda principale. 

2 Impostare le loro proprieta Name. 

3 Impostare la proprieta Visible per ciascun controllo immagine a false. 

4 Impostare la proprieta Picture di ciascuna immagine alia bitmap desiderata 
tramite l'editor Picture dall'Object Inspector. 

I controlli immagine sono invisibili quando viene eseguita l'applicazione. 

Aggiunta di immagini a un elenco di stringhe 

Dopo aver aggiunto immagini grafiche ad un'applicazione, e possibile associarle alle 
stringhe di un elenco. E possibile aggiungere gli oggetti tutti in un volta, come le 
stringhe, o associare gli oggetti alle stringhe esistenti. II metodo preferito e quello di 
aggiungere oggetti e stringhe contemporaneamente, se si hanno a disposizione tutti i 
dati necessari. 

L'esempio seguente mostra come si possono aggiungere immagini ad un elenco di 
stringhe. L'esempio fa parte di un'applicazione file manager in cui, insieme ad una 
lettera per ciascuna unita valida, viene aggiunto una bitmap che indica il tipo di 
ciascuna unita. II gestore di evento OnCreate ha questo formato: 

void __fastcall TFMForm: :FormCreate(TObject *Sender) 

{ 

int Addedlndex; 

char DriveName[4] = "A:\\"; 

for (char Drive = 'A'; Drive <= 'Z'; Drive++) // try all possible drives 
{ 

DriveName[0] = Drive- 
switch (GetDriveType(DriveName) ) 
{ 

case DRIVE_REM0VABLE : / / add a list item 
DriveName[l] = ' \ ' ; // temporarily make drive letter into string 
Addedlndex = DriveList->ltems->AddOb]ect (DriveName, 

Floppy->Picture->Graphic) ; 
DriveName[l] = ':' // replace the colon 
break ; 

case DRIVE_FIXED: // add a list item 
DriveName [1] = 1 \ ' ; // temporarily make drive letter into string 
Addedlndex = DriveList->ltems->AddObject (DriveName, 

Fixed->Picture->Graphic) ; 
DriveName[l] = ':' // replace the colon 
break ; 

case DRIVE_REMOTE : / / add a list item 
DriveName [1] = 1 \ ' ; // temporarily make drive letter into string 
Addedlndex = DriveList->ltems->AddObject (DriveName, 

Network->Picture->Graphic) ; 
DriveName[l] = ':' // replace the colon 
break ; 

} 

if ((int) (Drive - 'A') == getdisk(l) // current drive? 
DriveList->ItemIndex = Addedlndex; // then make that the current list item 

} 

} 
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Disegno di elementi owner-draw 

Le viste elenco e i controlli pagina hanno una proprieta di nome OwnerDmw che 
attiva o disattiva il tracciamento predefinito. Invece, il sistema operativo genera 
eventi per ciascun elemento visibile del controllo. L'applicazione gestisce gli eventi 
per disegnare gli elementi. 

Per disegnare gli elementi in un controllo owner-draw, occorre fare quanta descritto 
qui di seguito per ciascun elemento visibile del controllo. Si deve usare un unico 
gestore di evento per tutti gli elementi. 

1 Dimensionare, se necessario, l'elemento. 

Gli elementi con le stesse dimensioni (per esempio, con uno stile casella di 
riepilogo di IsOwnerDrawFixed), non richiedono alcun dimensionamento. 

2 Disegno dell'elemento. 

Dimensionamento degli elementi owner-draw 



Prima di dare all'applicazione la possibility di disegnare tutti gli elementi di un 
controllo owner-draw variabile, il sistema operativo genera un evento a misura di 
elemento. Questo evento comunica all'applicazione dove l'elemento appare sul 
controllo. 

C++Builder determina le dimensioni dell'elemento (generalmente, sono grandi a 
sufficienza per visualizzare il testo dell'elemento con il font corrente). L'applicazione 
pud gestire l'evento e modificare il rettangolo scelto. Per esempio, se si prevede di 
sostituire una bitmap per il testo dell'elemento, e bene modificare il rettangolo in 
modo che abbia le dimensioni del bitmap. Se si desidera un bitmap e il testo, si deve 
regolare il rettangolo in modo che sia abbastanza grande per entrambi. 

Per modificare le dimensioni di un elemento owner-draw, occorre collegare un 
gestore all'evento a misura di elemento nel controllo owner-draw. II nome 
dell'evento varia in funzione del controllo. Le caselle di riepilogo e quelle combinate 
usano OnMeasureltem. Le griglie non hanno alcun evento a misura di elemento. 

II dimensionamento di un evento ha due importanti parametri: il numero di indice 
dell'elemento e le dimensioni dell'elemento stesso. Le dimensioni sono variabili: 
l'applicazione puo crearle piu piccole o piu grandi. Le posizioni degli elementi 
successivi dipendono dalle dimensioni di quelli precedenti. 

Per esempio, in una casella di riepilogo owner-draw variabile, se l'applicazione 
imposta l'altezza del primo elemento a cinque pixel, il secondo elemento distera sei 
pixel, e cosi via. Sia nelle caselle di riepilogo sia in quelle combinate l'unico aspetto 
dell'elemento che l'applicazione puo cambiare e l'altezza. La larghezza e sempre 
quella del controllo. 

Le griglie owner-draw non possono modificare le dimensioni delle loro celle quando 
disegnano. Le dimensioni di ciascuna riga e di ciascuna colonna vengono impostate 
prima di disegnare dalle proprieta ColWidths e RowHeights. 
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II seguente codice, collegato all'evento OnMeasureltem di una casella di riepilogo 
owner-draw, aumenta l'altezza di ciascun elemento dell'elenco per contenere la sua 
bitmap associata. 

void __fastcall TForml : :ListBoxlMeasureItem(TWinCoiitrol *Control, int Index, 
int &Height) // note that Height is passed by reference 

{ 

int BitmapHeight = ( (TBitmap *)ListBoxl->Items->Objects [Index] ) ->Height + 2; 
// make sure list item has enough room for bitmap (plus 2) 
if (BitmapHeight > Height) 
Height = BitmapHeight; 

} 

Occorre convertire gli elementi dalla proprieta Objects nell'elenco di stringhe. Objects 
e una proprieta di tipo TObject che pertanto puo contenere qualsiasi tipo di oggetto. 
Quando si recuperano gli oggetti dall'array, occorre riconvertirli nel tipo effettivo 
degli elementi. 

Disegno di elementi owner-draw 



Quando un'applicazione ha bisogno di disegnare o di ridisegnare un controllo 
owner-draw, il sistema operativo genera eventi draw-item per ciascun elemento 
visibile del controllo. A seconda del controllo, l'elemento puo anche ricevere gli 
eventi di tracciamento per l'elemento nel suo complesso o per i singoli sottoelementi. 

Per disegnare un elemento di un controllo owner-draw, si deve collegare un gestore 
all'evento draw-item per quel controllo. 

I nomi degli eventi per il disegno personalizzato di solito iniziano con uno dei 
seguenti modi: 

• OnDraw, come OnDrawItem o OnDrawCell 

• OnCustomDraw, come OnCustomDrawItem 

• OnAdvancedCustomDraw, come OnAdvancedCustomDrawItem 

L'evento draw-item contiene i parametri che indentificano l'elemento da disegnare, il 
rettangolo in cui disegnare e solitamente alcune informazioni sullo stato 
dell 'elemento (per esempio, se l'elemento ha il fuoco). L'applicazione gestisce ciascun 
evento rappresentando l'elemento appropriato nel rettangolo dato. 

Per esempio, il codice seguente mostra come disegnare gli elementi in una casella di 
riepilogo che ha delle bitmap associate a ciascuna stringa. II codice collega questo 
gestore all'evento OnDrawItem per la casella di riepilogo: 

void fastcall TForml: :ListBoxlDrawItem(TWinControl *Control, int Index, 

TRect &Rect, TOwnerDrawState State) 

TBitmap *Bitmap = (TBitmap *) ListBoxl->Items->Objects [Index] ; 
ListBoxl->Canvas->Draw(R.Left, R.Top + 2, Bitmap); // draw the bitmap 
ListBoxl->Canvas->TextOut (R.Left + Bitmap->Width + 2, R.Top + 2, 
ListBoxl->Items->Strings [Index] ) ; // and write the text to its right 

} 
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Creazione di applicazioni, 
componenti e librerie 

In questo capitolo viene fornita una panoramica sull'uso di C++Builder per la 
creazione di applicazioni, librerie e componenti. 

Creazione di applicazioni 



C++Builder e usato principalmente per la progettazione e la costruzione dei seguenti 
tipi di applicazioni: 

• Applicazioni GUI 

• Applicazioni per console 

• Applicazioni di servizio (solo per applicazioni Windows) 

• Package e DLL 

Generalmente, le applicazioni GUI hanno un'interfaccia di facile impiego. Le 
applicazioni per console vengono eseguite da una finestra della console. Le 
applicazioni di servizio sono eseguite come servizi Windows. Questi tipi di 
applicazioni vengono compilati come eseguibili con codice di avvio. 

Si possono creare altri tipi di progetto, come package e DLL, che portano alia 
realizzazione di package o di librerie collegabili dinamicamente. Queste applicazioni 
producono un codice eseguibile senza codice di avvio. Fare riferimento al paragrafo 
"Creazione di package e di DLL" on page 7-10. 

Applicazioni GUI 



Un'applicazione con interfaccia utente grafica (GUI) viene progettata utilizzando 
funzionalita grafiche come finestre, menu, finestre di dialogo e altre funzionalita che 
la rendono facile da usare. Quando si compila un'applicazione GUI, viene generato 
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un file eseguibile con codice di avvio. L'eseguibile generalmente fornisce la 
funzionalita di base del programma, tanto che i programmi piu semplici sono 
costituiti esclusivamente da un file. E possibile estendere l'applicazione chiamando le 
DLL, i package e gli altri file di supporto dall'eseguibile. 

C++Builder offre due modelli di applicazione UI: 

• Single document interface (SDI) 

• Multiple document interface (MDI) 

Oltre che con il modello di implementazione delle applicazioni, il comportamento 
del progetto in fase di progettazione e di esecuzione dell'applicazione pud essere 
modificato tramite le opzioni di progetto dell'IDE. 

Modelli di interfaccia utente 

Le schede possono essere implementate come schede MDI (Multiple document 
interface) o SDI (Single document interface). In un'applicazione MDI e possibile 
aprire all'intemo di un'unica finestra genitore piu di un documento o finestra figlio. 
Cio vale per applicazioni come i fogli di lavoro o gli elaboratori testo. 
Un'applicazione SDI, invece, generalmente contiene un'unica vista del documento. 
Per rendere una scheda un'applicazione SDI, occorre impostare la proprieta 
FormStyle dell'oggetto Form afsNormal. 

Per ulteriori informazioni sullo sviluppo dell'interfaccia utente per un'applicazione, 
consultare il Capitolo 8, "Sviluppo dell'interfaccia utente dell'applicazione". 

Applicazioni SDI 

Per creare una nuova applicazione SDI: 

1 Selezionare File I New I Other per richiamare la finestra di dialogo New Items. 

2 Fare clic sulla pagina Projects e fare doppio clic su SDI Application. 

3 Fare clic su OK. 

Per impostazione predefinita, la proprieta FormStyle dell'oggetto Form efsNormal, 
chioschi C++Builder presuppone che tutte le nuove applicazioni siano di tipo SDI. 

Applicazioni MDI 

Per creare una nuova applicazione MDI: 

1 Selezionare File I New I Other per richiamare la finestra di dialogo New Items. 

2 Fare clic sulla pagina Projects e fare doppio clic su MDI Application. 

3 Fare clic su OK. 

Le applicazioni MDI richiedono una maggiore pianificazione e sono in un certo senso 
piu complesse da progettare di quelle SDI. Le applicazioni MDI generano finestre 
figlio che risiedono all'intemo della finestra client; la scheda principale contiene le 
schede figlio. Per specificare se una scheda e figlio (fsMDIForm) o la scheda principale 
(fsMDIChild), occorre impostare la proprieta FormStyle dell'oggetto TForm. E 
consigliabile definire una classe base per le schede figlio e derivare ogni scheda figlio 
da questa classe, per evitare di dover ridefinire le proprieta della scheda figlio. 



Creazione di applicazioni, componenti e librerie 7-2 



Creazione di applicazioni 



Le applicazioni MDI spesso includono sul menu principale una finestra popup che 
contiene elementi quali Cascade e Tile per la visualizzazione di piu finestre in 
modalita differenti. Quando una finestra figlio viene ridotta a icona, la sua icona e 
situata nella scheda MDI genitore. 

Per riassumere cio che e necessario fare per creare le finestre per l'applicazione MDI: 

1 Creare la scheda della finestra principale o finestra MDI genitore. Impostare la sua 
proprieta FormStyle afsMDIForm. 

2 Creare un menu per la finestra principale che include File I Open, File I Save e 
Window che abbia gli elementi Cascade, Tile e Arrange All. 

3 Creare le schede MDI figlio e impostare le loro proprieta FormStyle afsMDIChild. 

Impostazioni delle opzioni per TIDE, il progetto e la compilazione 

Per specificare le diverse opzioni per il progetto, utilizzare il comando Project I 
Options. Per maggiori informazioni, consultare la Guida in linea. 

Impostazione delle opzioni predefinite del progetto 

Per cambiare le opzioni predefinite che valgono per tutti i progetti, si deve ricorrere 
alia finestra di dialogo Project Options e contrassegnare la casella Default nell'angolo 
in basso a destra. Per impostazione predefinita, tutti i nuovi progetti utilizzeranno le 
opzioni correnti selezionate. 

Modelli di programmazione 



I modelli di programmazione sono scheletri di strutture comunemente utilizzate, che 
e possibile aggiungere al codice sorgente e quindi completare. In C++Builder sono 
inclusi alcuni modelli di codice standard, come quelli per gli array, per le classi, per 
la dichiarazioni di funzioni, nonche molte istruzioni. 

E possibile anche scrivere dei modelli propri per codificare delle strutture di impiego 
frequente. Ad esempio, se si desidera utilizzare nel codice un ciclo for, si puo inserire 
il seguente modello: 

for (; ;) 

{ 

} 

Per inserire un modello di codice nel Code editor, premere Ctrl-] e selezionare il 
modello di codice che si intende utilizzare. A questa raccolta e possibile aggiungere 
anche dei propri modelli. Per aggiungere un modello: 

1 Scegliere il comando Tools I Editor Options. 

2 Fare clic sul separatore Code Insight. 

3 Nei sezione Template, fare clic su Add. 

4 Dopo Shortcut name scrivere un nome per il modello, immettere una breve 
descrizione del nuovo modello e fare clic su OK. 
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5 Aggiungere il codice del modello nella casella di testo Code. 

6 Fare clic su OK. 

Applicazioni per console 



Le applicazioni per console sono programmi a 32-bit che vengono eseguiti senza 
un'interfaccia grafica, solitamente in una finestra per console. Queste applicazioni di 
solito non richiedono un'interazione con l'utente ed eseguono un numero limitato di 
funzioni. 

Per creare una nuova applicazione per console: 

1 Selezionare l'opzione di menu File I New I Other ,quindi nella finestra di dialogo 
New Items selezionare l'opzione Console Wizard. 

2 Nella finestra di dialogo Console Wizard, selezionare l'opzione Console 
Application, scegliere il tipo di file sorgente (C o C++) per il modulo principale del 
progetto, o specificare un file esistente che contenga una funzione main o 
winmain, quindi fare clic sul pulsante OK. 

C++Builder creera un file di progetto per questo tipo di file sorgente e visualizzera il 
Code editor. 

Utilizzo di VCL e CLX in applicazioni per console 

Quando si crea una nuova applicazione per console, l'IDE non crea una nuova 
scheda. Viene visualizzato solo il Code editor. 

Nelle applicazioni per console e possibile tuttavia utilizzare la VCL e la CLX. Per fare 
cio occorre indicare nel Console Wizard che si intende utilizzare la VCL o la CLX 
(selezionare l'opzione Use VCL oppure Use CLX). Se nel Wizard non si indica che si 
vuole utilizzare la VCL o la CLX, in seguito non sara piu possibile utilizzare alcuna 
classe della VCL o della CLX in quella applicazione. Se si tenta di farlo, il linker 
generera una serie di errori. 

Le applicazioni per console dovrebbero gestire tutte le eccezioni per impedire alle 
finestre di visualizzare una finestra di dialogo durante la sua esecuzione. 

Applicazioni di servizio 



Le applicazioni di servizio accettano richieste dalle applicazioni client, elaborano tali 
richieste e restituiscono informazioni all'applicazione client. Solitamente vengono 
eseguite in background, con poca o nulla interazione con l'utente. Esempi di 
applicazioni di servizio sono i server Web, i server FTP o di posta. 

Per creare un'applicazione che implementi un servizio Win32: 

1 Scegliere File I New I Other e fare doppio clic su Service Application nella finestra di 
dialogo New Items. In questo modo si aggiunge una variabile di nome Application 
al progetto, che e di tipo T Service Application. 
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2 Apparira una finestra Service che corrisponde a un servizio (TService). Per 
implementare il servizio, occorre impostarne le proprieta e i gestori di evento 
nell'Object Inspector. 

3 Scegliendo File I New I Other e selezionando Service dalla finestra di dialogo New 
Items, e possibile aggiungere ulteriori servizi all'applicazione del server. Non e 
possibile aggiungere servizi ad un'applicazione che non sia di servizio. Anche se e 
possibile aggiungere un oggetto TService, l'applicazione non generera gli eventi 
necessari, ne effettuera le chiamate appropriate ad Windows a favore del servizio. 

4 Una volta creata Y applicazione di servizio, e possibile installarne i servizi con 
Service Control Manager (SCM). Le altre applicazioni potranno quindi attivare tali 
servizi inviando delle richieste a SCM. 

Per installare i servizi dell'applicazione, eseguire il programma utilizzando l'opzione 
/INSTALL. L'applicazione installera i suoi servizi e terminera, emettendo un 
messaggio di conferma dell'avvenuta installazione dei servizi. Se si esegue 
l'applicazioni di servizio utilizzando l'opzione /SILENT e possibile evitare la 
visualizzazione del messaggio di conferma. 

Per disinstallare i servizi, eseguire l'applicazione dalla riga comandi utilizzando 
l'opzione /UNINSTALL. (E possibile utilizzare anche l'opzione /SILENT per 
sopprimere il messaggio di conferma emesso in fase di disinstallazione). 

Esempio Questo servizio ha un TServerSocket la cui porta e impostata a 80. Questa e la porta 
predefinita dei browser Web per effettuare richieste ai server Web e dei server Web 
per fornire risposte ai browser. Questo particolare esempio produce un documento 
di testo di nome WebLogxxx.log (dove xxx e ThreadID) nella directory C:\Temp. Ci 
deve essere un unico server in ascolto nella porta stabilita, in modo che, se c'e un 
server Web, si avra la certezza che non sta ascoltando (il servizio viene interrotto). 

Per vedere il risultato: aprire un browser Web sulla macchina locale e immettere 
'localhost' (senza virgolette) per l'indirizzo. Probabilmente il browser si disattivera, 
ma a questo punto sara disponibile un file di nome Weblogxxx.log nella directory 
C:\Temp. 

1 Per creare l'esempio, scegliere il comando File I New I Other e selezionare nella 
finestra di dialogo New Items l'opzione Service Application. Appare la finestra 
Servicel. 

2 Aggiungere alia finestra del servizio (Servicel) un componente ServerSocket 
prelevandolo dalla pagina Internet della Component palette). 

3 Aggiungere alia classe TServicel un membro dati privato di tipo TMemoryStream. 
L' intestazione della unit dovrebbe assomigliare al seguente: 

// 

♦ifndef UnitlH 
♦define UnitlH 
// 

♦include <SysUtils.hpp> 
♦include <Classes .hpp> 
♦include <SvcMgr.hpp> 
♦include <ScktComp.hpp> 

// 
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class TServicel : public TService 

{ 

..published :// IDE-managed Components 
TServerSocket *ServerSocketl; 
private:// User declarations 

TMemoryStream *Stream; // add this line here 
public:// User declarations 

fastcall TServicel (TComponent* Owner); 

PServiceController __fastcall GetServiceController(void) ; 

friend void __stdcall ServiceController (unsigned CtrlCode) ; 

}; 

// 

extern PACKAGE TServicel *Servicel; 

// 

#endif 

4 Selezionare ServerSocket 1, il componente aggiunto al passo 1. Fare doppio clic 
sull'evento OnClientRead nell'Object Inspector ed aggiungere il seguente gestore di 
evento: 

void __fastcall TServicel: :ServerSocketlClientRead(TObject *Sender, 
TCustomWmSocket *Socket) 

{ 

char *Buffer = NULL; 

int len = Socket->ReceiveLength ( ) ; 

while (len > 0) 

{ 

try 

{ 

Buffer = (char *)malloc (len) ; 
Socket->ReceiveBuf ( (void *)Buffer, len); 
Stream- >Write (Buffer, len); 

} 

finally 

{ 

free (Buff er) ; 

} 

Stream->Seek(0, soFromBeginning) ; 
AnsiString LogFile = "C: WTempWWebLog" ; 

LogFile = LogFile + lntToStr(ServiceThread->ThreadlD) + ".log"; 
Stream->SaveToFile (LogFile) ; 

} 

} 

5 Infine, selezionare Servicer facendo clic nell'area del client della finestra (non sul 
ServiceSocket). Fare doppio clic sull'evento OnExecute nell'Object Inspector ed 
aggiungere il seguente gestore di evento: 

void __fastcall TServicel: : ServicelExecute (TService *Sender) 

{ 

Stream = new TMemoryStream () ; 
try 

{ 

ServerSocketl->Port = 80; // WWW port 
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ServerSocketl->Active = true; 
while ( ITerminated) 

ServiceThread->ProcessRequests (true) ; 
ServerSocketl->Active = false; 

} 

finally 

{ 

delete Stream; 

} 

} 

Quando si scrivono le applicazioni di servizio, bisogna far attenzione a: 

• Thread dei servizi 

• Proprieta del nome del servizio 

• Debug delle applicazioni di servizio 

Le applicazioni di servizio sono solo per l'ambiente Windows. 



Thread dei servizi 

Ogni servizio ha un proprio thread (TServiceThread), cosicche se l'applicazione 
implementa piu di un servizio, occorre verif icare che l'implementazione dei servizi 
sia a prova di thread. TServiceThread e progettato in modo che sia possibile 
implementare il servizio nel gestore di evento TService OnExecute. II thread del 
servizio ha un proprio metodo Execute che contiene un ciclo che chiama i gestori 
OnStart e OnExecute del servizio prima di prendere in considerazione nuove 
richieste. 

Dal momenta che i servizi richiesti possono richiedere molto tempo per 
l'elaborazione e l'applicazione che fornisce il servizio pud ricevere richieste 
simultanee da piu di un client, e piu efficiente derivare un nuovo thread (da TThread, 
non da TServiceThread) per ciascuna richiesta e spostare l'implementazione di quel 
servizio al metodo Execute del nuovo thread. Cio consente al ciclo Execute del thread 
di servizio di elaborare in continuazione le nuove richieste, senza dover attendere 
che il gestore OnExecute del servizio termini. L'esempio seguente illustra quanto 
detto finora. 

Esempio Questo servizio emette un segnale acustico ogni 500 millisecondi daU'interno del 
thread standard. Esso gestisce la sospensione, la prosecuzione e l'interruzione del 
thread quando al sevizio viene chiesto di sospenderlo, continuarlo o interromperlo. 

1 Scegliere File I New I Other e selezionare dalla finestra di dialogo New Items 
l'opzione Service Application. Apparira la finestra Servicel. 

2 Nel file header della unit, dichiarare un nuovo discendente di TThread di nome 
TSparky Thread. Questo e il thread che esegue i compiti affidati al servizio. La 
dichiarazione dovrebbe essere come segue: 

class TSparkyThread : public TThread 
{ 

private : 
protected ; 

void __fastcall Executed; 

public : 
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__fastcall TSparkyThread (bool CreateSuspended); 

}; 

3 Nel file .cpp della unit, creare una variabile globale per un'istanza di 
TSparky Thread: 

TSparkyThread *SparkyThread; 

4 Aggiungere il codice seguente al file .cpp del costruttore TSparkyThread: 

__fastcall TSparkyThread: : TSparkyThread (bool CreateSuspended) 
: TThread (CreateSuspended) 

{ 
} 

5 Aggiungere il codice seguente al file .cpp del metodo Execute di TSparkyThread (la 
funzione di thread): 

void __fastcall TSparkyThread: : Executed 

{ 

while (! Terminated) 
{ 

Beep ( ) ; 
Sleep (500) ; 

} 

} 

6 Selezionare la finestra del servizio (Servicel), e fare doppio clic sull'evento OnStart 
nell'Object Inspector. Aggiungere il seguente gestore di evento OnStart: 

void __fastcall TServicel: : ServicelStart (TService *Sender, bool SStarted) 

{ 

SparkyThread = new TSparkyThread ( false ) ; 
Started = true; 

} 

7 Fare doppio clic sull'evento OnContinue nell'Object Inspector. Aggiungere il 
seguente gestore di evento OnContinue: 

void __fastcall TServicel: :ServicelContinue(TService *Sender, bool &Continued) 
{ 

SparkyThread->Resume ( ) ; 
Continued = true; 

} 

8 Fare doppio clic sull'evento OnPause nell'Object Inspector. Aggiungere il seguente 
gestore di evento OnPause: 

void _fastcall TServicel: : ServicelPause (TService *Sender, bool SPaused) 

{ 

SparkyThread->Suspend( ) ; 
Paused = true; 

} 

9 Infine, fare doppio clic sull'evento OnStop nell'Object Inspector e aggiungere il 
seguente gestore di evento OnStop: 

void __fastcall TServicel: :ServicelStop (TService *Sender, bool ^Stopped) 

{ 
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SparkyThread->Terminate ( ) ; 
Stopped = true; 

} 

Quando si sviluppano applicazioni server, la scelta di generare un nuovo thread 
dipende dalla natura del servizio da fornire, dal numero anticipato di connessioni e 
dal numero previsto di processori nel computer che esegue il servizio. 

Proprieta del nome del servizio 

La VCL fornisce le classi per la creazione di applicazioni di servizio per la 
piattaforma Windows (non disponibile per applicazioni multipiattaforma). Ne fanno 
parte TService e TDependency. Quando si utilizzano queste classi, e possibile fare 
confusione tra le diverse proprieta del nome. In questa sezione vengono descritte le 
differenze. 

I servizi hanno nomi utente (denominati Service start names) associati a password, 
nomi per la visualizzazione nelle finestre manager e editor, e nomi veri e propri (il 
nome del servizio). Le dipendenze possono essere servizi o possono essere caricate 
ordinando i gruppi. Esse anche nomi e nomi di visualizzazione. E, dal momento che 
gli oggetti service sono derivati da TComponent, essi derivano la proprieta Name. Le 
sezioni successive riportano le proprieta dei nomi: 

Proprieta di TDependency 

DisplayName di TDependency e sia un nome di visualizzazione sia il nome vero e 
proprio del servizio. Coincide quasi sempre con la proprieta Name di TDependency. 

Proprieta Name di TService 

La proprieta Name di TService viene ereditata da TComponent.E il nome del 
componente ed anche il nome del servizio. Per le dipendenze che sono servizi, questa 
proprieta coincide con le proprieta Name e DisplayName di TDependency. 

DisplayName di TService e il nome visualizzato nella finestra Service Manager. Spesso 
e diverso dal nome effettivo del servizio {TServicer.Name, TDependencyr.DisplayName, 
TDependency::Name). Si noti che il DisplayName per la dipendenza e il DisplayName 
per il servizio generalmente sono diversi. 

I Service start names si distinguono sia dai nomi di visualizzazione del servizio sia 
dai nomi effettivi del servizio. Un ServiceStartName e il nome utente inserito nella 
finestra di dialogo Start selezionata dal Service Control Manager. 

Debug delle applicazioni di servizio 

E possibile eseguire il debug di applicazioni di servizio collegandosi al processo 
dell'applicazione di servizio quando e gia in esecuzione (cioe, avviando per prima 
cosa il servizio e quindi collegandosi al debugger). Per agganciarsi al processo 
dell'applicazione di servizio, selezionare il comando Run I Attach To Process e 
selezionare nella finestra di dialogo che verra attivata l'applicazione di servizio. 

In alcuni casi, questo secondo metodo potrebbe non riuscire poiche si hanno diritti 
insufficienti. In questo caso, si pud utilizzare Service Control Manager per abilitare il 
servizio a a funzionare con il debugger: 
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1 Per prima cosa, nella posizione del file di registro di Windows indicata di seguito, 
creare una chiave di nome Image File Execution Options: 

HKEY_LOCAL_MACHINE \ SOFTWARE \Mi cro so f t \Wi ndows NT\CurrentVersion 

2 Creare una sottochiave avente lo stesso nome del servizio (ad esempio, 
MYSERV.EXE). A questa sottochiave aggiungere un valore di nome Debugger e di 
tipo REG_SZ. Come valore della stringa, utilizzare il nome di percorso completo 
delBCB.exe. 

3 Nel programma Services control panel, selezionare il servizio, fare clic su Startup e 
selezionare l'opzione Allow Service to Interact with Desktop. 

Sui sistemi Windows NT, e possibile utilizzare un altro metodo per eseguire il debug 
di applicazioni di servizio. Tuttavia, questo approccio puo risultare complicato in 
quanto richiede tempi di esecuzione molto brevi: 

1 Per prima cosa, avviare l'applicazione nel debugger. Attendere qualche secondo 
affinche l'applicazione sia caricata completamente. 

2 Avviare rapidamente il servizio dal pannello di controllo o dalla riga comandi: 

start MyServ 

II servizio deve essere awiato rapidamente (entro 15-30 secondi dall'avvio 
dell'applicazione) altrimenti, se non viene awiato alcun servizio, l'applicazione 
terminera. 

Creazione di package e di DLL 



Le librerie a collegamento dinamico (DLL) sono moduli di codice compilato che 
funziona in abbinamento con un eseguibile per fornire funzionalita ad una 
applicazione. E possibile creare delle DLL nei programmi multipiattaforma.Tuttavia, 
in ambiente Linux, le DLL (e i package) vengono ricompilati come oggetti condivisi. 

I package sono speciali DLL usate dalle applicazioni C++Builder, dall'IDE o da 
entrambe. Esistono due tipi di package: i package di esecuzione e quelli di 
progettazione. I package di esecuzione forniscono funzionalita ad un programma 
durante il sua funzionamento. I package di progettazione estendono la funzionalita 
dell'IDE. 

Le DLL e le librerie dovrebbero gestire tutte le eccezioni per evitare la 
visualizzazione di errori e di awertimenti mediante le finestre di dialogo di 
Windows. 
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Nel file di progetto della libreria e possibile introdurre le seguenti direttive al 
compilatore: 

Tabella 7.1 Direttive al compilatore per le librerie 
Direttiva al compilatore Descrizione 

($LIBPREFIX 'string" 



($LIBSUFFIX 'string') 



(SUBVERSION 
'string'} 



Aggiunge uno specifico prefisso al nome del file di output. Ad esempio, si 
potrebbe specificare |$LIBPREFIX 'del'} per un package di progettazione 
oppure utilizzare {$LIBPREFIX ' ' } per eliminare completamente il prefisso. 

Aggiunge uno specifico suffisso al nome del file di output prima 
dell'estensione. Ad esempio, utilizzare j$SOSUFFIX '-2.13' } in 
something.cpp per generare something-2.L3.bpl. 

Aggiunge una seconda estensione al nome del file di output dopo 
l'estensione .bpl. Ad esempio, utilizzare |$SOSUFFIX '-2.13' } in 
something.cpp per generare something-2.L3.bpl. 



Per ulteriori informazioni sui package, consultare il Capitolo 15, "Uso di package e di 
componenti". 

Quando usare i package e le DLL 



Per la maggior parte delle applicazioni scritte in C++Builder, i package forniscono 
una maggiore flessibilita e sono piu facili da creare delle DLL. Tuttavia, ci sono 
diverse situazioni in cui le DLL risultano piu adatte dei package per i progetti: 

• Quando il modulo di codice verra chiamato da applicazioni non C++Builder. 

• Se si estende la funzionalita di un server Web. 

• Quando si crea un modulo di codice che deve essere utilizzato da sviluppatori 
terzi. 

• Quando il progetto e un contenitore OLE. 

Non si possono passare le informazioni di tipo in esecuzione (RTTI) da una DLL a 
un'altra, oppure da una DLL a un eseguibile. Questo perche le DLL gestiscono tutte 
le proprie informazioni sui simboli. Se e necessario passare un oggetto TStrings da 
una DLL, utilizzando un operatore is oppure as, bisogna creare un package invece di 
una DLL. I package condividono le informazioni sui simboli. 



Uso delle DLL in C++Builder 



Le DLL di Windows possono essere utilizzate nelle applicazioni C++Builder proprio 
come nelle normali applicazioni C++. 

Per caricare in modo statico una DLL al caricamento di un'applicazione C++Builder, 
occorre collegare all'applicazione C++Builder il file di libreria di importazione per la 
DLL durante il linking. Per aggiungere una libreria di importazione a 
un'applicazione C++Builder, scegliere Project I Add to Project e selezionare il file .LIB 
che si desidera aggiungere. 



Creazione di applicazioni, componenti e librerie 7-11 



Creazione di DLL in C + + Builder 

Le funzioni esportate della DLL vengono quindi rese disponibili all'applicazione. 

Mediante il modificatore declspec ( dllimport ) creare un prototipo delle funzioni 

DLL utilizzate dall'applicazione: 

__declspec (dllimport) return_type imported_function_name{parameters) ; 

Per caricare in modo dinamico una DLL durante l'esecuzione di un'applicazione 
C++Builder, includere la libreria di importazione, esattamente come nel caso del 
caricamento statico, e impostare l'opzione del linker per il caricamento ritardato nella 
pagina Project I Options I Advanced Linker. Si puo anche ricorrere alia funzione API 
di Windows LoadLibraryO , che carica la DLL, e poi alia funzione API GetProcAddressO, 
che ricava i puntatori alle singole funzioni che si vogliono utilizzare. 

Ulteriori informazioni sull'impiego delle DLL si trovano in Microsoft® Win32 SDK 
Reference. 

Creazione di DLL in C++Builder 



La creazione di DLL in C++Builder e analoga alia creazione in C++ standard: 

1 Scegliere il comando File I New I Other per visualizzare la finestra di dialogo New 
Items. 

2 Fare doppio clic sull'icona DLL Wizard. 

3 Scegliere il tipo di sorgente per il modulo principale (C o C++). 

4 Se si vuole che l'entry point della DLL sia DllMain, secondo lo stile MSVC++, 
selezionare l'opzione VC++ style, altrimenti, come entry point sara utilizzato 
DLLEntryPoint. 

5 Fare clic su Use VCL o su Use CLX per creare una DLL contenente componenti 
della VCL o della CLX. L'opzione e disponibile solo per moduli sorgente in C++. 
Consultare "Creazione di DLL contenenti componenti VCL e CLX" on page 7-13. 

6 Se si vuole che la DLL sia multi-thread, selezionare l'opzione Multi-threaded. 

7 Fare clic su OK. 

Le funzioni esportate presenti nel codice devono essere identificate mediante il 

modificatore declspec (dllexport) proprio come awiene in Borland C++ o in 

Microsoft Visual C++. Per esempio, il codice seguente e consentito sia in C++Builder 
sia in altri compilatori Windows C++: 

// MyDLL.cpp 

double dblValue (double ) ; 
double halfValue (double ) ; 

extern "C" __declspec (dllexport) double changeValue (double, bool); 

double dblValue (double value) 

{ 

return value * value; 

}; 

double halfValue (double value) 
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{ 

return value / 2.0; 

} 

double changeValue (double value, bool whichOp) 
{ 

return whichOp ? dblValue (value) : halfValue (value) ; 

} 

Nel codice precedente viene esportata la funzione changeValue, che viene resa 
pertanto disponibile alle applicazioni che la chiamano. Le funzioni dblValue e 
halfValue sono interne, per cui non possono essere chiamate dall'estemo della DLL. 

Ulteriori informazioni sulla creazione di DLL si trovano in Microsoft® Win32 SDK 
Reference. 

Creazione di DLL contenenti componenti VCL e CLX 



Uno dei punti di forza delle DLL e il fatto che una DLL creata con un determinate 
strumento di sviluppo puo spesso essere utilizzata da un'applicazione scritta con 
uno strumento di sviluppo differente. Quando la DLL contiene dei componenti VCL 
(per esempio, delle schede) che devono essere utilizzate dall'applicazione chiamante, 
bisogna preparare delle routine di interfaccia esportate che utilizzino le convenzioni 
di chiamata standard, evitare il mangling dei nomi di C++, mentre non e richiesto che 
l'applicazione chiamante supporti la libreria VCL o CLX per poter funzionare. Per 
creare componenti VCL o CLX che possano essere esportati, utilizzare i package di 
runtime. Per ulteriori informazioni, consultare il Capitolo 15, "Uso di package e di 
componenti". 

Si supponga, per esempio, di voler creare una DLL per visualizzare questa semplice 
finestra di dialogo: 




II codice della DLL della finestra di dialogo e il seguente: 

// DLLMAIN.H 

// 

♦lfndef dllMainH 
♦define dllMainH 

// 

♦include <Classes .hpp> 
♦include <vcl\Controls.hpp> 
♦include <vcl\StdCtrls .hpp> 
♦include <vcl\Forms .hpp> 

// 

class TYesNoDialog : public TForm 
{ 
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__published : // IDE-managed Components 
TLabel *LabelText; 
TButton *YesButton; 
TButton *NoButton; 

void __fastcall YesButtonClickfTObject * Sender ) ; 

void __fastcall NoButtonClick(TObject *Sender) ; 
private: // User declarations 

bool returnValue; 
public: // User declarations 

virtual __fastcall TYesNoDialog(TComponent *0wner) ; 

bool __fastcall GetReturnValue ( ) ; 

}; 

// exported interface function 

extern "C" __declspec (dllexport ) bool invokeYesNoDialogd ; 

// 

extern TYesNoDialog *YesNoDialog; 

// 

#endif 



// DLLMAIN.CPP 

// 

♦include <vcl\vcl.h> 
♦pragma hdrstop 

♦include "dllMain.h" 

// 

♦pragma resource "*.dfm" 
TYesNoDialog *YesNoDialog; 

// 

__fastcall TYesNoDialog: : TYesNoDialog (TComponent *0wner) 
: TForm (Owner) 

{ 

returnValue = false; 

} 

// 

void __fastcall TYesNoDialog: :YesButtonClick(TObject *Sender) 

{ 

returnValue = true; 
Closed ; 

} 

// 

void __fastcall TYesNoDialog: :NoButtonClick(TObject *Sender) 

{ 

returnValue = false; 
Closed ; 

} 

// 

bool __fastcall TYesNoDialog: : GetReturnValue () 

{ 

return returnValue; 

} 

// 
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// exported standard C++ interface function that calls into VCL 
bool invokeYesNoDialogO 

{ 

bool return Value; 

TYesNoDialog *YesNoDialog = new TYesNoDialog(NULL) ; 
YesNoDialog->ShowModal () ; 

returnValue = YesNoDialog->GetReturnValue ( ) ; 

delete YesNoDialog; 
return returnValue; 

} 

// 

II codice riportato nell'esempio visualizza la finestra di dialogo e, se viene premuto il 
pulsante "Yes", memorizza il valore true nel membro dati privato returnValue. In 
caso contrario, returnValue ha valore false. La funzione pubblica GetReturnValueO 
recupera il valore corrente di returnValue. 

Per richiamare la finestra di dialogo e stabilire quale pulsante e stato premuto, 
l'applicazione chiamante chiama la funzione esportata InvokeYesNoDialogO. Questa 
funzione e dichiarata in DLLMAIN.H come funzione esportata utilizzando le 
convenzioni standard del C per il collegamento (in modo da evitare il mangling dei 
nomi di C++) e per la chiamata. La funzione e definita in DLLMAIN.CPP. 

Grazie all'utilizzo di una funzione C standard come interfaccia verso la DLL, 
qualsiasi applicazione chiamante, creata o meno in C++Builder, puo utilizzare la 
DLL. Le funzionalita VCL e CLX richieste per supportare la finestra di dialogo e 
collegata nella DLL stessa, e l'applicazione chiamante non ha bisogno di ulteriori 
informazioni a tale proposito. 

Si tenga presente che, quando si crea una DLL che utilizza la VCL o la CLX, i 
componenti necessari della VCL o della CLX vengono collegati alia DLL, dando 
luogo ad un certo appesantimento. L'impatto di tale appesantimento sulle 
dimensioni totali dell'applicazione puo essere ridotto al minimo combinando piu 
componenti in un'unica DLL, la quale necessita di una sola copia dei componenti di 
supporto della VCL o della CLX. 

Collegamento delle DLL 



E possibile impostare le opzioni del linker per le DLL utilizzando la pagina Linker 
della finestra di dialogo Project Options. La casella di controllo predefinita su questa 
pagina crea inoltre una libreria di importazione per la DLL. Se si effettua la 
compilazione dalla riga comandi, chiamare il linker, ILINK32.EXE, utilizzando 
l'opzione -Tpd. Ad esempio: 

ilink32 /c /aa /Tpd c0d32 . obj mydll.obj, mydll.dll, mydll.map, import32.1ib cw32mt.lib 

Se occorre generare una libreria di importazione, utilizzare anche l'opzione -Gi. 

Se occorre, e possibile creare una libreria di importazione utilizzando il programma 
di utilita dalla riga comandi IMPLIB.EXE. Ad esempio: 

implib mydll.lib mydll.dll 
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Per maggiori informazioni sulle diverse opzioni per il collegamento delle DLL e 
sull'utilizzo delle stesse con altri moduli collegati in modo statico o dinamico alia 
libreria di runtime, consultare la Guida in linea. 



Scrittura di applicazioni database 



Uno dei punti di forza di C++Builder e il suo supporto per la creazione di 
applicazioni database evolute. C++Builder possiede una serie di strumenti interni 
che consentono di collegarsi a server SQL e a database Oracle, Sybase, InterBase, 
MySQL, MS-SQL, Informix e DB2, fornendo una condivisione trasparente dei dati tra 
le varie applicazioni. 

C++Builder include molti componenti per accedere ai database e rappresentare le 
informazioni in essi contenute. Sulla Component palette, i componenti database sono 
raggruppati in base alia funzione svolta e secondo il meccanismo di accesso di dati. 

Tabella 7.2 Pagine di database sulla Component palette 

Pagina della 
Component 

palette Contenuti 

BDE Componenti che utilizzano Borland Database Engine (BDE), una vasta API per 

interagire con i database. BDE supporta una vasta gamma di funzioni ed e 
fornito con molti programmi di utilita tra i quali Database Desktop, Database 
Explorer, SQL Monitor e BDE Administrator. Per i particolari, vedere il Capitolo 
24, "Uso di Borland Database Engine". 

ADO Componenti che utilizzano ActiveX Data Objects (ADO), sviluppato da 

Microsoft, per accedere alle informazioni di un database. Sono disponibili molti 
driver ADO per la connessione a vari server di database. I componenti basati su 
ADO permettono di integrare l'applicazione in un ambiente ADO. Per i 
particolari, vedere il Capitolo 25, "Operazioni con componenti ADO". 

dbExpress Componenti multipiattaforma che utilizzano dbExpress per accedere alle 

informazioni nel database. I driver dbExpress consentono un accesso rapido ai 
database ma, per eseguire gli aggiornamenti, devono essere utilizzati con 
TClientDataSet e TDataSetProvider. Per i dettagli vedere il Capitolo 26, "Uso di 
dataset unidirezionali". 

InterBase Componenti per l'accesso diretto ai database InterBase, senza passare attraverso 

uno strato separato di motore. Per ulteriori informazioni sull'utilizzo dei 
componenti InterBase, consultare la Guida in linea. 

Data Access Componenti, come TClientDataSet e TDataSetProvider, che possono essere 
utilizzati con qualsiasi meccanismo di accesso ai dati. Per informazioni sui 
dataset client, consultare il Capitolo 27, "Utilizzo dei dataset client". Per 
informazioni sui provider, consultare il Capitolo 28, "Uso di componenti 
provider". 

Data Controls Controlli data-aware che possono accedere alle informazioni provenienti da un 
datasource. Consultare il Capitolo 19, "Uso dei controlli dati". 



Quando si progetta un'applicazione database, e necessario decidere che meccanismo 
di accesso ai dati utilizzare. Ogni meccanismo di accesso ai dati differisce dagli altri 
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per ampiezza di supporto funzionale, per semplicita di distribuzione e nella 
disponibilita di driver per il supporto dei diversi server di database. 

Per informazioni dettagliate sull'uso di C++Builder per creare sia applicazioni client 
database sia server di applicazioni, consultare la Parte II, "Sviluppo di applicazioni 
database" in questo stesso manuale. Per informazioni sulla ditribuzione, fare 
riferimento a "Distribuzione di applicazioni database" a pagina 17-6. 

Non tutte le edizioni di C++Builder includono il supporto per i database. 



Distribuzione di applicazioni database 



C++Builder fornisce il supporto per la creazione di applicazioni database distribuite 
grazie all'utilizzo di un set coordinato di componenti. Le applicazioni database 
distribuite possono essere costruite su un gran numero di protocolli di 
comunicazione, compresi DCOM, TCP/IP e SOAP. 

Per ulteriori informazioni sulla costruzione di applicazioni database distribuite, 
consultare il Capitolo 29, "Creazione di applicazioni multi-tier". 

La distribuzione di applicazioni database spesso richiede la fornitura di Borland 
Database Engine (BDE) in aggiunta ai file dell'applicazione. Per informazioni sulla 
distribuzione del BDE, consultare "Distribuzione di applicazioni database" a 
pagina 17-6. 

Creazione di applicazioni per Web server 



Le applicazioni per Web server sono applicazioni che vengono eseguite su server per 
la distribuizione su Internet di contenuti Web come pagine Web HTML o documenti 
XML. Tra gli esempi di applicazioni per Web server vi sono quelle per controllare 
l'accesso a un sito Web, per generare ordini di acquisto o per rispondere a richieste di 
informazioni. 

Sfruttando le seguenti tecnologie C++Bilder si possono creare vari tipi di 
applicazioni per Web server: 

• Web Broker 

• WebSnap 

• InternetExpress 

• Web Services 

Utilizzo di Web Broker 



Si utilizza Web Broker (detto anche architettura NetCLX) per creare applicazioni per 
Web server, come applicazioni CGI o librerie a collegamento dinamico (DLL). Queste 
applicazioni per Web server possono contenere qualsiasi componente di tipo non 
visuale. I componenti raccolti nella pagina Internet della Component palette 
permettono di creare gestori di evento, di costruire da programma documenti HTML 
o XML e di trasferirli al client. 
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Per creare una nuova applicazione per server Web utilizzando l'architettura Web 
Broker, selezionare il comando File I New I Other, quindi Web Server Application nella 
finestra di dialogo New Items. Infine, si deve scegliere il tipo di applicazione per 
server Web: 



Tabella 7.3 Applicazioni per Web server 
Descrizione 



Tipo di applicazione 
Web server 



ISAPI and NSAPI 
Dynamic Link Library 



CGI Stand-alone 
executable 



Win-CGI Stand-alone 
executable 



Apache Shared 
Module (DLL) 



Web App Debugger 

Stand-alone 

executable 



Le applicazioni per server Web ISAPI o NSAPI sono DLL caricate dal 
server Web. Le informazioni di richiesta del client vengono passate alia 
DLL come struttura e valutate da TISAPIApplication. Ogni messaggio di 
richiesta e gestito in un thread di esecuzione separato. 

La selezione di questo tipo di applicazione provoca l'aggiunta dell'heder 
di libreria dei file di progetto e di tutte le voci necessarie all'elenco uses e 
alia clausola export del file di progetto. 

Le applicazioni per server Web CGI sono applicazione per console che 
ricevono richieste dal client sull'input standard, le elaborano e 
restituiscono il risultato al server sull'output standard affinche le invii al 
client. 

Le applicazioni per server Web Win-CGI sono applicazioni Windows 
che ricevono richieste dai client mediante un file di impostazioni di 
configuazione (INI) scritto dal server, e scrivono il risultato in un file che 
il server restituisce al client. II file INI e valutato da TCGIApplication. 
Ogni messaggio di richiesta e gestito da un'istanza separata 
dell'applicazione. 

La selezione di questo tipo di applicazione imposta il progetto come una 
DLL. Le applicazioni per server Web Apache sono DLL caricate dal 
server Web. Le informazioni vengono passate alia DLL, elaborate e 
restituite al client dal server Web. 

La selezione di questo tipo di applicazione imposta l'ambiente per lo 
sviluppo e il collaudo di applicazioni per server Web. Le applicazioni 
Web App Debugger sono file eseguibili caricati dal server Web. Questo 
tipo di applicazione non e destinato alia distribuzione. 



Le applicazioni CGI e Win-CGI usano un maggior numero di risorse di sistema sul 
server, pertanto e preferibile che le applicazioni complesse vengano create come 
applicazioni ISAPI, NSAPI o DLL Apache. Se si scrivono applicazioni 
multipiattaforma, per lo sviluppo per Web server si deve selezionare l'opzione CGI 
stand-alone oppure Apache Shared Module (DLL). Sono le stesse opzioni che 
compaiono quando si creano applicazioni WebSnap e Web Service. 

Per ulteriori informazioni sulla costruzione di applicazioni per server Web, 
consultare il Capitolo 32, "Creazione di applicazioni server per Internet". 

Creazione di applicazioni WebSnap 



WebSnap fornisce un insieme di componenti e di wizard per la realizzazione di Web 
server evoluti che interagiscono con i Web browsers. I componenti WebSnap 
generano contenuti HTML o altri contenuti MIME per pagine Web. WebSnap e per lo 
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sviluppo lato server. Attualmente, WebSnap non pud essere utilizzato in applicazioni 
multipiattaforma. 

Per creare una nuova applicazione WebSnap, selezionare il comando File I New I 
Other, quindi selezionare la pagina WebSnap nella finestra di dialogo New Items. 
Scegliere WebSnap Application. Infine, si deve scegliere il tipo di applicazione per 
server Web: (ISAPI/NSAPI, CGI, Win-CGI, Apache). Per i dettagli, consultare la 
Tabella 7.3, "Applicazioni per Web server". 

Per ulteriori informazioni su WebSnap, consultare il Capitolo 34, "Creazione di 
applicazioni Web Server con WebSnap". 

Utilizzo di InternetExpress 



IntemetExpress e un set di componenti che arricchisce l'architettura di base per 
applicazioni per Web server, consentendole di agire come client di un application 
server. Si utilizza InternetExpress per applicazioni in cui i client basati su browser 
prelevano dati da un provider, risolvono gli aggiornamenti sul provider, pur essendo 
in esecuzione su un client. 

Le applicazioni InternetExpress generano pagine HTML che contengono un misto di 
HTML, XML e javascript. HTML determina la disposizione e l'aspetto delle pagine 
visualizzate nel browser dell'utente finale. XML codifica i pacchetti dati e i pacchetti 
delta che rappresentano le informazioni del database. Javascript permette ai controlli 
HTML di interpretare e trattare i dati dei pacchetti dati XML sulla macchina client. 

Per ulteriori informazioni su InternetExpress, consultare "Creazione di applicazioni 
Web con InternetExpress" a pagina 29-33. 

Creazione di applicazioni Web Services 



I Web Services sono applicazioni modulari indipendenti che possono essere diffuse e 
richiamate in una rete (come il World Wide Web). I Web Services dispongono di 
interfacce ben definite che descrivono i servizi forniti. Si utilizzano per produrre o 
usufruire su Internet di servizi programmabili , impiegando standard emergenti 
come XML, XML Schema, SOAP (Simple Object Access Protocol) e WSDL (Web 
Service Definition Language). 

I Web Services utilizzano SOAP, un protocollo standard a basso ingombro per lo 
scambio di informazioni in ambiente distribuito. Utilizzano HTTP come protocollo di 
comunicazione e XML per codificare le chiamate a procedure remote. 

E possibile utilizzare C++Builder per costruire i server che implementano i Web 
Services e i client che chiamano questi servizi. E' possibile scrivere dei client per 
server arbitrari che implementano dei Web Services che rispondono a messaggi 
SOAP, nonche server C++Builder che pubblicano Web Services utilizzabili da client 
arbitrari. 

Per ulteriori informazioni sui Web Services fare riferimento al Capitolo 36, "Utilizzo 
dei Web Services". 
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Scrittura di applicazioni con COM 



COM e l'acronimo di Component Object Model, un'architettura di oggetti distribuiti 
basata su Windows, progettata per fornire l'interoperabilita degli oggetti grazie ad 
una serie di routine predefinite dette interfacce. Le applicazioni COM utilizzano 
oggetti che vengono implementati da un processo diverso, o, se si utilizza DCOM, su 
una macchina diversa. E possibile anche utilizzare COM+, ActiveX e Active Server 
Pages. 

e un modello software basato su componenti e indipendente dal linguaggio che 
consente l'interazione fra componenti software e applicazioni eseguiti su piattaforma 
Windows. L'aspetto chiave di COM e la sua capacita di consentire la comunicazione 
fra componenti, fra applicazioni e fra client e server tramite interfacce chiaramente 
definite. Le interfacce consentono ai client di chiedere a un componente COM quali 
funzioni supporta in fase di esecuzione. Per dotare il componente di ulteriori 
funzioni, e sufficiente aggiungere una opportuna interfaccia. 

Utilizzo di COM e DCOM 



C++Builder ha classi e wizard che semplificano la creazione degli elementi essenziali 
per applicazioni COM, OLE o ActiveX. E possibile creare client o server COM che 
implementano oggetti COM, Automation server (tra cui Active Server Objects), 
controlli ActiveX o ActiveForms. COM serve anche da base per altre tecnologie, come 
Automation, per i controlli ActiveX, Active Documents e Active Directories. 

L'uso di C per creare applicazioni basate su COM offre una vasta gamma di 
possibilita, dalla possibilita di apportare migliorie ai progetti software, grazie all'uso 
delle interfacce all'interno delle applicazioni, alia creazione di oggetti in grado di 
interagire con altri oggetti API di sistema basati su COM, quali le estensioni alia Shell 
di Win9x e il supporto multimediale per DirectX. Le applicazioni possono accedere 
alle interfacce dei componenti COM, presenti sullo stesso computer su cui risiede 
l'applicazione o che esistono su un altro computer della rete, mediante un 
meccanismo detto Distributed COM (DCOM). 

Per ulteriori informazioni su COM e sui controlli ActiveX, consultare il Capitolo 38, 
"Panoramica sulle tecnologie COM", Capitolo 43, "Creazione di un controllo 
ActiveX", e il paragrafo "Distribuzione di un'applicazione client come controllo 
ActiveX" a pagina 29-32. 

Per ulteriori informazioni su DCOM, consultare "Uso di connessioni DCOM" a 
pagina 29-10. 

Utilizzo di MTS e C0M+ 



Le applicazioni COM possono essere potenziate con servizi speciali per la gestione di 
oggetti in un ambiente distribuito su vasta scala. Questi servizi comprendono servizi 
di transazione, sicurezza e gestione delle risorse forniti da Microsoft Transaction 
Server (MTS) su versioni di Windows precedenti Windows 2000), oppure COM+ (per 
Windows 2000 e versioni successive). 
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Per ulteriori informazioni su MTS e COM+, consultare il Capitolo 44, "Creazione di 
oggetti MTS o COM+" e il paragrafo "Uso di moduli dati transazionali" a 
pagina 29-7. 

Utilizzo dei moduli dati 



Un modulo dati puo essere considerato come una speciale scheda contenente 
componenti non visuali. Tutti i componenti di un modulo dati potrebbero essere 
collocati su schede comuni assieme a controlli visuali. Ma se si sta progettando di 
riutilizzare gruppi di database e di oggetti di sistema, oppure se si desidera isolare 
quelle parti dell'applicazione che gestiscono la connettivita al database e le regole di 
gestione, allora i moduli dati rappresentano un pratico strumento organizzativo. 

Vi sono numerosi tipi di moduli dati, compresi quelli standard, quelli remoti, i 
moduli Web, i moduli applet e i servizi, a seconda della versione di C++Builder di 
cui si dispone. Ogni tipo di modulo dati risponde a uno scopo particolare. 

• I moduli dati standard risultano particolarmente utili per applicazione database 
single-tier e two-tier, ma possono essere utilizzati per organizzare i componenti 
non visuali in qualsiasi applicazione. Per ulteriori informazioni, consultare 
"Creazione e modifica di moduli dati standard" a pagina 7-22. 

• I moduli dati remoti formano la base di un application server nelle applicazioni 
database multi-tier. Essi non sono presenti in tutte le versioni. Oltre a conservare i 
componenti non visuali nell'application server, i moduli dati remoti espongono 
l'interfaccia che i client usano per comunicare con l'application server. Per 
ulteriori informazioni sul loro impiego, consultare "Aggiunta di un modulo dati 
remoto a un progetto di application server" a pagina 7-25. 

• I moduli Web costituiscono la base delle applicazioni per Web server. Oltre a 
contenere i componenti che creano il contenuto dei messaggi di risposta HTTP, 
essi gestiscono la distribuzione dei messaggi HTTP provenienti dalle applicazioni 
client. Per ulteriori informazioni sull'utilizzo dei moduli Web, consultare il 
Capitolo 32, "Creazione di applicazioni server per Internet". 

• I moduli Applet costituiscono la base per le applet del pannello di controllo. Oltre 
a conservare i controlli non visuali che implementano l'applet del pannello di 
controllo, definiscono le proprieta che determinano in che modo l'icona 
dell'applet viene visualizzata nel pannello di controllo e includono gli eventi 
chiamati quando gli utenti eseguono l'applet. Per maggiori informazioni sui 
moduli applet, consultare la Guida in linea. 

• I servizi incapsulano singoli servizi in un' applicazione di servizio NT. Oltre a 
contenere tutti i controlli non visuali utilizzati per implementare un certo servizio, 
i servizi comprendono gli eventi che vengono chiamati quando il servizio viene 
attivato o interrotto. Per ulteriori informazioni sui servizi, consultare 
"Applicazioni di servizio" a pagina 7-4. 
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Creazione e modifica di moduli dati standard 



Per creare un modulo dati standard destinato a un progetto, scegliere File I New I 
Data Module. C++Builder apre un modulo dati contenitore nel desktop, visualizza il 
file unit relativo al nuovo modulo nel Code editor, e aggiunge il modulo al progetto 
corrente. 

In fase di progettazione, un modulo dati assomiglia a una scheda Delphi standard, 
con uno sfondo bianco e senza griglia di allineamento. Come nel caso delle schede, in 
un modulo si possono collocare componenti non visuali presi dalla Component 
palette e modificarne le proprieta nell'Object Inspector. E possibile ridimensionare 
un modulo dati per alloggiare i componenti che vi vengono aggiunti. 

Facendo clic destro su un modulo si visualizza un menu contestuale. La seguente 
tabella riassume le opzioni del menu contestuale di un modulo dati. 

Tabella 7.4 Opzioni del menu contestuale dei moduli dati 



Voce di menu 


Funzione 


Edit 


Visualizza un menu contestuale mediante il quale e possibile 
tagliare, copiare, incollare, cancellare e selezionare i componenti 
del modulo dati. 


Position 


Allinea i componenti non visuali alia griglia invisibile del 
modulo (Align To Grid), oppure secondo i criteri indicati nella 
finestra di dialogo Alignment (Align). 


Tab Order 


Permette di modificare la sequenza di accesso mediante il tasto 
Tab ai vari componenti e il conseguente spostamente del fuoco. 


Creation Order 


Permette di modificare l'ordine con cui vengono creati all'avvio i 
componenti di accesso ai dati. 


Revert to Inherited 


Abbandona le modifiche apportate a un modulo ereditato da un 
altro modulo nell'Object Repository, e ritorna al modulo 
originario ereditato. 


Add to Repository 


Registra nell'Object Repository un collegamento al modulo dati. 


View as Text 


Visualizza la rappresentazione testuale delle proprieta del 
modulo dati. 


Text DFM 


Commuta tra i formati (binario o testo) in cui viene salvato 
questo particolare file di scheda. 



Per maggiori informazioni sui moduli dati, consultare la Guida in linea. 



Attribuzione del nome a un modulo dati e al relativo file unit 

La barra del titolo di un modulo dati visualizza il nome del modulo. II nome 
predefinito e "DataModuleN", in cui N e un numero che rappresenta il numero di 
unit piu basso non ancora utilizzato nel progetto. Ad esempio, se si awia un nuovo 
progetto, e si aggiungere ad esso un modulo prima di fare qualsiasi altra operazione, 
il nome predefinito del modulo dati sara "DataModule2". II file unit corrispondente a 
DataModulel sara o "Unit2." 

In fase di progettazione, si dovrebbe cambiare il nome ai moduli dati e ai file unit 
corrispondenti per renderli piu descrittivi. In particolare, e bene rinominare i moduli 
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dati che si aggiungono all'Object Repository per evitare conflitti di nome con altri 
moduli dati presenti nel Repository, oppure con altre applicazioni che utilizzano i 
moduli. 

Per rinominare un modulo dati: 

1 Selezionare il modulo. 

2 Modificare la proprieta Name del modulo nell'Object Inspector. 

Non appena la proprieta Name nell'Object Inspector non e piu evidenziata, il nuovo 
nome del modulo appare nella barra del titolo. 

Modificando il nome di un modulo dati in progettazione se ne modifica il nome della 
variabile nella sezione interface del codice. Vengono modificate anche tutte le 
clausole uses che fanno riferimento al nome nelle dichiarazioni di procedura. E 
necessario invece modificare manualmente qualsiasi riferimento al modulo dati nel 
codice scritto in prima persona. 

Per cambiare nome al file unit di un modulo dati: 

1 Selezionare il file unit. 

Posizionamento e assegnazione del nome ai componenti 

I componenti non visuali vengono collocati in un modulo dati esattamente come i 
componenti visuali su una scheda. Si fa clic sul componente voluto sulla pagina 
appropriata della Component palette, quindi si fa clic nel modulo dati per collocare il 
componente. In un modulo dati, non si possono mettere controlli visuali, come le 
griglie. Se si tenta di farlo, viene visualizzato un messaggio di errore. 

Per facilita di impiego, in un modulo dati i componenti vengono visualizzati con i 
loro nomi. Quando si colloca un componente, C++Builder gli assegna un nome 
generico che ne identifica il tipo,seguito dalla cifra 1. Ad esempio, il componente 
TDataSource adotta il nome DataSourcel. Questo facilita la selezione di componenti 
specifici di cui si desiderano gestire proprieta e metodi. 

In certi casi, conviene assegnare al componente un nome diverso che ne riflette il tipo 
e lo scopo a cui e destinato. 

Per modificare il nome di un componente in un modulo dati: 

1 Selezionare il componente. 

2 Modificare la proprieta Name del componente nell'Object Inspector. 

Non appena la proprieta Name nell'Object Inspector non e piu evidenziata, il nuovo 
nome del componente appare sotto la sua icona nel modulo dati. 

Ad esempio, si supponga che l'applicazione database utilizzi la tabella CUSTOMER. 
Per accedere alia tabella, servono almeno due componenti di accesso ai dati: un 
componente datasource (TDataSource) e un componente tabella (TClientDataSet). 
Quando si collocano questi componenti nel modulo dati, C++Builder assegna loro i 
nomi DataSourcel e ClientDataSetl. Per riflettere sia il tipo di componente sia il 
database cui essi accedono, CUSTOMER, si potrebbero modificare questi nomi in 
CustomerSource e Customer! able. 
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Utilizzo delle proprieta e degli eventi dei componenti di un modulo dati 

La collocazione dei componenti in un modulo dati ne centralizza il comportamento 
rispetto all'intera applicazione. Ad esempio, si possono utilizzare le proprieta dei 
componenti dataset, come TCUentDataSet, per controllare i dati disponibili per i 
componenti datasource che utilizzano questi dataset. Impostando a True la proprieta 
ReadOnly di un dataset, si impedisce agli utenti di modificare i dati visualizzati nel 
controllo data-aware visuale di una scheda. E possibile anche richiamare il Fields 
editor relativamente a un dataset facendo doppio clic su ClientDataSetl, per limitare i 
campi all'interno di una tabella o di una query a disposizione del datasource, e di 
conseguenza a disposizione dei controlli data-aware sulle schede. Le proprieta che 
vengono impostate sui componenti inclusi in un modulo dati si ripercuotono 
coerentemente su tutte le schede nell'applicazione che utilizzano quel modulo. 

Oltre a definirne le proprieta, si possono scrivere dei gestori di evento per i 
componenti. Ad esempio, gli eventi che interessano un componente TDataSource 
sono tre: OnDataChange, OnStateChange e OnUpdateData. Un componente 
TCUentDataSet ha piu di 20 potenziali eventi.E possibile utilizzarli per creare un 
insieme coerente di regole di gestione che governano il trattamento dei dati in tutta 
l'applicazione. 

Creazione di regole di gestione in un modulo dati 

Oltre alia scrittura di gestori di evento per i componenti di un modulo dati, si 
possono codificare i metodi direttamente nel file unit di un modulo dati. Questi 
metodi possono essere applicati come regole di gestione alle schede che utilizzano il 
modulo dati. Per esempio, si supponga di scrivere una procedura che esegue la 
chiusura contabile mensile, trimestrale o annuale. Si puo chiamare la procedura da 
un gestore di evento di un componente del modulo dati. 

Accesso a un modulo dati da una scheda 



Per associare i controlli visuali su una scheda con un modulo dati, per prima cosa e 
necessario aggiungere il file header del modulo dati al file .cpp della scheda. 
L'operazione puo essere eseguita in diversi modi: 

• Nell'editor di codice, aprire il file unit della scheda e includere il file header del 
modulo dati usando la direttiva #include. 

• Fare clic sul file unit della scheda, scegliere il comando File I Include Unit,Hdr, 
quindi immettere il nome del modulo oppure sceglierlo dalla casella di riepilogo 
nella finestra di dialogo Use Unit. 

• Per componenti database, nel modulo dati fare clic su un componente di dataset o 
di query per aprire il Fields editor e trascinare i campi esistenti dall'editor sulla 
scheda. C++Builder chiedera conferma della volonta di aggiungere il modulo alia 
scheda, quindi creera i controlli (come le caselle di testo) per i campi. 

Ad esempio, se si e aggiunto al modulo dati il componente TCUentDataSet, fare 
doppio clic su esso per aprire il Fields editor. Selezionare un campo e trascinarlo sulla 
scheda. Viene visualizzato un componente casella di modifica. 
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Poiche il datasource non e ancora definite C++Builder aggiunge alia scheda un 
nuovo componente data-source, DataSourcel, e imposta a DataSourcel la proprieta 
DataSource della casella di modifica. II datasource imposta automaticamente la sua 
proprieta DataSet al componente dataset ClientDataSetl del modulo dati. 

Aggiungendo un componente TDataSource al modulo dati, e possibile definire il 
datasource prima di trascinare un campo sulla scheda. Impostare la proprieta DataSet 
del datasource a ClientDataSetl. Dopo avere trascinato un campo sulla scheda, 
appare la casella di modifica con la proprieta TDataSource gia impostata a 
DataSourcel. In questo modo, il modello di accesso ai dati si presenta piu "pulito". 

Aggiunta di un modulo dati remote a un progetto di application server 



Alcune versioni di C++Builder consentono di aggiungere moduli dati remoti a progetti 
di application server. Un modulo dati remoto ha un'interfaccia a cui possono 
accedere i client di un'applicazione multi-tier attraverso la rete. 

Per aggiungere un modulo dati remoto a un progetto: 

1 Selezionare File I New I Other. 

2 Nella finestra di dialogo New Items selezionare la pagina Multitier. 

3 Fare doppio clic sull'icona Remote Data Module per aprire il wizard Remote Data 
Module. 

Una volta aggiunto a un progetto un modulo dati remoto, e possibile utilizzarlo come 
un qualsiasi modulo dati standard. 

Per informazioni sulle applicazioni database multi-tier, consultare il Capitolo 29, 
"Creazione di applicazioni multi-tier". 

Utilizzo dell'Object Repository 



L'Object Repository (attivato tramite il comando Tools I Repository) semplifica la 
condivisione di schede, di finestre di dialogo, frame e di moduli dati. Inoltre, mette a 
disposizione tmodelli per i nuovi progetti e wizard che guidano l'utente nella 
creazione di schede e progetti. II repository e contenuto in BCB.DRO (presente per 
impostazione predefinita nella directory BIN), un file di testo contenente i riferimenti 
agli elementi che appaiono nelle finestre di dialogo Repository e New Items. 

Condivisione di elementi aM'interno di un progetto 



E possibile condividere gli elementi all'interno di un progetto senza aggiungerli 
all' Object Repository. Quando si attiva la finestra di dialogo New Items (mediante il 
comando File I New I Other), e possibile vedere una pagina che riporta il nome del 
progetto corrente. Questa pagina elenca tutte le schede, le finestre di dialogo e i 
moduli dati inclusi nel progetto. E possibile derivare un nuovo elemento da un 
elemento esistente e personalizzarlo in base alle proprie esigenze. 
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Aggiunta di elementi all'Object Repository 



E possibile aggiungere i propri progetti, le proprie schede, riquadri e i propri moduli 
dati a quelli gia disponibili nell'Object Repository. Per aggiungere un elemento 
all'Object Repository, 

1 Nel caso l'elemento sia un progetto o contenuto in un progetto, aprire il progetto. 

2 Nel caso di un progetto, scegliere il comando Project I Add To Repository. Nel caso 
sia una scheda o un modulo dati, fare clic destro sull'elemento e scegliere il 
comando Add To Repository. 

3 Immettere una descrizione, un titolo e l'autore. 

4 Decidere su quale pagina della finestra di dialogo New Items si vuole che appaia 
l'elemento, quindi scrivere il nome della pagina oppure selezionarla dalla casella 
combinata Page. Se si scrive il nome di una pagina inesistente, C++Builder creera 
una nuova pagina. 

5 Scegliere Browse per selezionare un'icona che rappresentera l'oggetto nell'Object 
Repository. 

6 Scegliere OK. 

Condivisione di oggetti in un team di lavoro 



E possibile condividere oggetti all'interno del proprio gruppo di lavoro o di sviluppo 
rendendo disponibile in rete il repository. Per utilizzare un repository condiviso, tutti 
i membri del team devono indicare per l'opzione Shared Repository della finestra di 
dialogo Environment Options la stessa directory: 

1 Scegliere il comando Tools I Environment Options. 

2 Sulla pagina Preferences, individuare il pannello Shared Repository. Nella casella 
di testo Directory, immettere la directory in cui si desidera ubicare il repository 
condiviso. Accertarsi di specificare una directory accessibile a tutti i membri del 
team. 

La prima volta che si aggiungera un elemento al repository, C++Builder creera nella 
directory indicata per lo Shared Repository un file di nome BCB.DRO, nel caso non 
ne esista gia uno. 

Utilizzo di un elemento dell'Object Repository in un progetto 



Per accedere agli elementi nell'Object Repository, scegliere il comando File I New I 
Other. Apparira la finestra di dialogo New Items che mostra tutti gli elementi 
disponibili. In base al tipo di elemento che si desidera utilizzare, saranno disponibili 
fino a tre opzioni per aggiungere l'elemento al progetto: 

• Copy 

• Inherit 

• Use 
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Copia di un elemento 

Scegliere l'opzione Copy per fare una copia esatta dell'elemento scelto e aggiungere 
la copia al progetto. Le successive modifiche apportate aU'elemento nell'Object 
Repository non influenzeranno la copia, come pure le modifiche apportate alia copia 
non influenzeranno l'elemento originale nell' Object Repository. 

L'opzione Copy e Tunica disponibile per modelli di progetto. 

Ereditare un elemento 

Scegliere l'opzione Inherit per derivare una nuova classe dall'elemento scelto 
nell'Object Repository e aggiungere la nuova classe al progetto. Quando si ricompila 
il progetto, qualsiasi modifica apportata aU'elemento nell'Object Repository si 
ripercuotera sulla classe derivata, in aggiunta alle modifiche apportate aU'elemento 
nel progetto. Le modifiche apportate alia classe derivata non si ripercuotono 
sull'elemento condiviso dell'Object Repository. 

L'opzione Inherit e disponibile per schede, finestre di dialogo e moduli dati ma non 
per modelli di progetto. E Yunica opzione disponibile per riutilizzare elementi 
all'interno dello stesso progetto. 

Utilizzo di un elemento 

Scegliere l'opzione Use quando si desidera che l'elemento scelto diventi parte del 
progetto. Le modifiche apportate aU'elemento nel progetto appariranno in tutti gli 
altri progetti a cui e stato aggiunto l'elemento mediante le opzioni Inherit o Use. 
Selezionare questa opzione con estrema attenzione. 

L'opzione Use e disponibile per schede, finestre di dialogo e moduli dati. 

Utilizzo di modelli di progetto 



I modelli (template) sono progetti predefiniti che e possibile utilizzare come punto di 
partenza per le proprie applicazioni. Per creare un nuovo progetto a partire da un 
modello: 

1 Scegliere il comando File I New I Other per visualizzare la finestra di dialogo New 
Items. 

2 Scegliere la pagina Projects. 

3 Selezionare il modello di progetto desiderata e scegliere OK. 

4 Nella finestra di dialogo Select Directory, specificare una directory per i file del 
nuovo progetto. 

C++Builder copia i file di modello nella directory specificata, in cui sara possibile 
modificarli. II modello originale del progetto non sara influenzato dalle eventuali 
modifiche. 
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Modifica di elementi condivisi 



Se si modifica un elemento nell'Object Repository, le modifiche si ripercuoteranno su 
tutti i successivi progetti che utilizzano l'elemento oltre che sui progetti esistenti a cui 
e stato aggiunto l'elemento mediante le opzioni Use o Inherit. Per evitare la 
propagazione di modifiche agli altri progetti, esistono varie alternative: 

• Copiare l'elemento e modificarlo solo nel progetto corrente. 

• Copiare l'elemento nel progetto corrente, modificarlo, quindi aggiungerlo al 
Repository con un nome differente. 

• A partire dall'elemento, creare un componente, una DLL, un modello di 
componente o un frame. Se si crea un componente o una DLL, e possibile 
condividerli con gli altri sviluppatori. 

Specifica di un progetto predefinito, di una nuova scheda e della 
scheda principale * 



Per impostazione predefinita, quando si sceglie il comando File I New I Application o 
File I New I Form, C++Builder visualizza una scheda vuota. E possibile modificare 
questo comportamento riconfigurando il Repository: 

1 Scegliere il comando Tools I Repository. 

2 Se si desidera specificare un progetto predefinito, selezionare la pagina Projects e 
scegliere un elemento in Objects. Quindi selezionare la casella di controllo New 
Project. 

3 If you want to specify a default form, select a Repository page (such as Forms), 
them choose a form under Objects. To specify the default new form (File I New I 
Form), select the New Form check box. To specify the default main form for new 
projects, select the Main Form check box. 

4 Fare clic su OK. 

Attivazione dell'Help nelle applicazioni 



Sia la VCL che CLX hanno la capacita di visualizzare l'Help delle applicazioni 
tramite un meccanismo basato su oggetti che permette l'inoltro delle richieste di Help 
a uno dei tanti visualizzatori di Help esterni. Per supportare questo sistema, 
un'applicazione deve includere una classe che implementa l'interfaccia 
ICustomHelpViewer (e, facoltativamente, una delle numerose interfacce da essa 
derivate), e quindi registrare se stessa mediante l'Help Manager globale. 

La VCL fornisce a tutte le applicazioni un'istanza di TWinHelpViewer, che 
implementa tutte queste interfacce e fornisce il collegamento tra le applicazioni e 
WinHelp. CLX richiede che venga fornita una propria implementazione. In 
Windows, le applicazioni CLX possono utilizzare la unit WinHelp Viewer, fornita 
come parte della VCL, se si collegano ad esso in modo statico — cioe, includendo 
quella unit come parte del progetto invece di collegarla con il package della VCL. 
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L'Help Manager gestisce una lista di visualizzatori registrati e passa loro le richieste 
in un processo bifase: prima chiede a ogni visualizzatore se puo fornire supporto per 
una particolare parola chiave dell'Help o contesto e quindi passa la richiesta Help al 
visualizzatore che ha risposto che puo fornire tale supporto. 

Se esiste piu di un visualizzatore che supporta la parola chiave, come nel caso di 
un'applicazione che ha registrato visualizzatori sia per WinHelp e per HYperHelp su 
Windows oppure sia per Man sia per Info su Linux, l'Help Manager puo visualizzare 
un riquadro di selezione attraverso cui l'utente dell'applicazione puo determinare 
quale visualizzatore di Help richiamare. Altrimenti, visualizza il primo sistema di 
Help che e stato rilevato. 

Interfacce per il sistema di Help 



II sistema di Help consente la comunicazione fra l'applicazione e i visualizzatori di 
Help mediante una serie di interfacce. Queste interfacce sono tutte definite in 
Helplntfs, che contiene anche l'implementazione dell'Help Manager. 

ICustomHelpViewer fornisce il supporto per la visualizzazione dell'Help in base a una 
parola chiave fornita, e per la visualizzazione di un indice che elenca tutti i file di 
Help disponibili in un particolare visualizzatore. 

IExtendedHelpViewer fornisce il supporto per la visualizzazione dell'Help in base a un 
contesto di Help numerico e per la visualizzazione di argomenti; nella maggior parte 
dei sistemi di Help, gli argomenti fungono da parole chiave ad alto livello (ad 
esempio, "IntToStr" potrebbe essere una parola chiave nel sistema di Help, mentre 
"String manipulation routines" potrebbe essere il nome di un argomento). 

ISpecialWinHelpViewer fornisce il supporto per la risposta a messaggi specializzati di 
WinHelp che un'applicazione in esecuzione in ambiente Windows potrebbe ricevere 
e che non sono facilmente generalizzabili. Di solito, solo le applicazioni che operano 
in ambiente Windows hanno la necessita di implementare questa interfaccia, e anche 
in questo caso l'implementazione e necessaria solo per le applicazioni che fanno un 
uso intensivo di messaggi non-standard di WinHelp. 

IHelpManager fornisce un meccanismo che consente al visualizzatore di Help di dare 
una risposta alio Help Manager dell'applicazione e di richiedere ulteriori 
informazioni. Uno IHelpManager viene ottenuto nel momento in cui il visualizzatore 
Help si registra. 

IHelpSystem fornisce un meccanismo attraverso il quale T Application passa le richiede 
di Help al sistema di Help. T Application ottiene un'istanza di un oggetto che 
implementa sia IHelpSystem sia IHelpManager ed esporta queste istanze sotto forma di 
proprieta; cio consente ad altro codice all'interno dell'applicazione di presentare 
direttamente, quando occorre, le richieste di Help. 

IHelpSelector fornisce un meccanismo attraverso cui il sistema di Help puo richiamare 
l'interfaccia utente per domandare quale visualizzatore di Help dovrebbe essere 
utilizzato, nei casi in cui vi sia piu di un visualizzatore in gradi di gestire una 
richiesta di Help, e per visualizzare un Indice generale. Questa capacita di 
visualizzazione non e incorporata direttamente nello Help Manager per poter avere 



Creazione di applicazioni, componenti e librerie 7-29 



Attivazione dell'Help nelle applicazioni 

un unico codice di Help Manager, indipendentemente da quale set di widget o 
libreria di classi si utilizzi. 

Implementazione di ICustomHelpViewer 



L'interfaccia ICustomHelpViewer contiene tre tipi di metodi: metodi utilizzati per 
comunicare con l'Help Manager informazioni a livello di sistema (ad esempio, 
informazioni non correlate a una particolare richiesta di Help); metodi relativi alia 
visualizzazione dell'Help in base a una parola chiave fornita dall'Help Manager; e 
metodi per la visualizzazione di un indice. 

Comunicazione con Help Manager 



ICustomHelpViewer fornisce tre funzioni che possono essere utilizzate per comunicare 
informazioni di sistema con l'Help Manager: 

• GetViewerName 

• NotifylD 

• ShutDown 

• SoftShutDown 

L'Help Manager chiama queste funzioni nelle seguenti circostanze: 

• AnsiString ICustomHelpViewer::GetViewerName() viene chiamata quando l'Help 
Manager vuole conoscere il nome del visualizzatore (ad esempio, se 
all'applicazione viene chiesto di visualizzare una lista di tutti i visualizzatori 
registrati). Queste informazioni vengono restituite per mezzo di una stringa, che 
deve ovviamente essere di tipo statico, (cioe, non puo cambiare durante 
l'operazione dell'applicazione). I set di caratteri multibyte non sono supportati. 

• void ICustomHelpViewer::NotifyID(const int ViewerlD) viene chiamata 
immediatamente dopo la registrazione in modo da fornire al visualizzatore un 
cookie univoco che la identifichi. Queste informazioni devono essere memorizzate 
per un successivo utilizzo; se il visualizzatore si chiude autonomamente (invece 
che in risposta a una notifica da parte dell'Help Manager), deve fornire all'Help 
Manager il cookie di identificazione, in modo che l'Help Manager possa rilasciare 
tutti i rif erimenti al visualizzatore. (II non fornire il cookie o il fornirne uno errato, 
fa si che l'Help Manager potenzialmente rilasci i riferimenti al visualizzatore 
errato.) 

• void ICustomHelpViewer ::ShutDowni) viene chiamato dall'Help Manager per 
chiedere al visualizzatore di Help di chiudere qualsiasi manifestazione 
esternamente visibile del sistema di Help (ad esempio, delle finestre che 
visualizzano informazioni della guida) senza pero scaricare il visualizzatore. 

• void ICustomHelpViewer::SoftShutDown() viene chiamata dall'Help Manager per 
informare il visualizzatore di Help che il Manager sta per essere chiuso e che tutte 
le risorse allocate dal visualizzatore di Help dovrebbero essere liberate. Si 
consiglia di delegare a questo metodo tutte le risorse da liberare. 
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Richiesta di informazioni all'Help Manager 



I visualizzatori di Help sono in comunicazione con l'Help Manager attraverso 
l'interfaccia IHelpManager, una cui istanza viene loro restituita quando vengono 
registrati con l'Help Manager. IHelpManager permette al visualizzatore Help di 
comunicare quattro cose: 

• Una richiesta dello handle di finestra del controllo attualmente attivo. 

• Una richiesta del nome del file di Help che l'Help Manager crede dovrebbe 
contenere la guida relativa al controllo attivo al momento. 

• Una richiesta del percorso per quel file di Help. 

• Una notifica che il visualizzatore Help si sta chiudendo in risposta a qualcosa 
diverso da una richiesta dall'Help Manager in tale senso. 

int IHelpManager: :GetHandle() viene chiamata dal visualizzatore di Help nel caso 
abbia bisogno di conoscere lo handle del controllo attualmente attivo; il risultato e un 
handle di finestra. 

AnsiString IHelpManager: :GetHandleQ viene chiamata dal visualizzatore di Help nel 
caso desideri conoscere il nome del file di Help che, stando al controllo corrente, 
dovrebbe contenere l'aiuto per il controllo. 

void IHelpManager: :Release() viene chiamata per notificare all'Help Manager che un 
visualizzatore di Help si sta scollegando. Non dovrebbe essere mai chiamata in 
risposta a una richiesta proveniente da IHelpManager::ShutDown(); viene utilizzata 
solo per notificare all'Help Manager di una sconnessione inaspettata. 

Visualizzazione di Help in base a parole chiave 



Di solito le richieste di aiuto arrivano dal visualizzatore Help o sotto forma di aiuto in 
base a una parola chiave, nel qual caso al visualizzatore viene richiesto di fornire un 
aiuto in base a una particolare stringa, oppure come aiuto in base al contesto, nel qual 
caso al visualizzatore viene richiesto di fornire un aiuto in base a un particolare 
identificativo numerico. 

I contesti numerici di aiuto sono la forma standard delle richieste di Help nelle 
applicazioni eseguite in ambiente Windows che utilizzano il sistema WinHelp; 
benche supportate dalla CLX, se ne sconsiglia l'utilizzo nelle applicazioni CLX 
perche la maggior parte dei sistemi di Help di Linux non sono in grado di 
comprenderle. 

Alle implementazioni di ICustomHelpViewer viene richiesto di fornire il supporto per 
richieste di aiuto in base a una parola chiave, mentre alle implementazioni 
IExtendedHelpViewer viene richiesto il supporto per le richieste di aiuto in base al 
contesto. 

ICustomHelpViewer fornisce tre metodi per la gestione di aiuto in base a una parola 
chiave: 

• UnderstandsKeyword 

• GetHelpStrings 

• ShowHelp 
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int__fastcall ICustomffelpViewer: :UnderstandsKeyword(const AnsiStrmg HelpString) 

e il primo dei tre metodi chiamati dall'Help Manager, il quale chiamera ogni 
visualizzatore di Help registrato passandogli la stessa stringa per chiedergli se e in 
grado di fornire un aiuto per quella stringa; il visualizzatore dovrebbe risponde con 
un valore integer che indica quante differenti pagine della guida puo visualizzare in 
risposta a quella richiesta di Help. Per determinare tale valore, il visualizzatore puo 
utilizzare un qualsiasi metodo- all'interno dell'IDE il visualizzatore HyperHelp 
gestisce il proprio indice e lo utilizza per la ricerca. Se il visualizzatore non e in grado 
di fornire un aiuto per questa parola chiave dovrebbe restituire zero. I numeri 
negativi vengono interpretati come se fossero zero, ma questo comportamento non e 
garantito nelle versioni successive. 

Classes: :TStringList*__fastcall ICustomHelpViewer: :GetHelpStrings (const AnsiString 
HelpString) 

viene chiamato dall'Help Manager nel caso vi sia piu di un visualizzatore in grado di 
fornire un aiuto su un argomento. II visualizzatore dovrebbe restituire uno 
TStringList liberato dall'Help Manager. Le stringhe nella lista restituita dovrebbero 
corrispondere alle pagine disponibili per quella parola chiave, ma le caratteristiche di 
quella mappatura possono essere determinate dal visualizzatore. Nel caso del 
visualizzatore WinHelp in Windows e del visualizzatore HyperHelp in Linux, 
l'elenco di stringhe contiene sempre esattamente una voce. HyperHelp fornisce una 
propria indicizzazione e la sua duplicazione in un'altra posizione produrrebbe una 
duplicazione senza puntatore. Nel caso del visualizzatore Man page (Linux), la lista 
di stringhe e formata da stringhe multiple, una per ogni sezione del manuale che 
contiene una pagina per quella parola chiave. 

void__fastcall ICustomHelpViewer: :ShowHelp (const AnsiString HelpString) 

viene chiamato dall'Help Manager nel caso abbia bisogno che il visualizzatore di 
Help visualizzi un aiuto per una particolare parola chiave. Questa e l'ultima 
chiamata a metodo dell'operazione; il sistema garantisce che non sara mai chiamato a 
meno che prima non venga chiamato il metodo UnderstandsKeyword. 

Visualizzazione degli indici 

ICustomHelpViewer fornisce due metodi relativi alia visualizzazione degli indici: 

• CanShowTableOfContents 

• ShowTableOf Contents 

II meccanismo del loro funzionamento e simile a quello delle operazioni di richiesta 
di help in base a una parola chiave: per prima cosa l'Help Manager interroga tutti i 
visualizzatori di Help chiamando ICustomHelpViewer::CanShowTableOfContents() e 
successivamente richiama un particolare visualizzatore di Help chiamando 

ICustomHelpViewer::ShowTableOjContents(). 

E perfettamente normale che un particolare visualizzatore si rifiuti di supportare 
richieste per la visualizzazione di un indice. Questo e il caso, ad esempio, del 
visualizzatore Man page, perche il concetto di indice non si addice alia modalita di 
funzionamento di Man page; il visualizzatore HyperHelp, invece, supporta un indice 
passando la richiesta di visualizzare l'indice direttamente a HyperHelp su Linux e a 
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WinHelp su Windows. Non e normale, tuttavia, che un'implementazione di 
ICustomHelpViewer risponda a una richiesta che perviene da CanShowTableOfContents 
con true e poi ignori le richieste che pervengono da ShowTableOfContents. 

Implementazione lExtendedHelpViewer 



ICustomHelpViewer fornisce solo un supporto diretto per Help basati su parole 
chiave. Alcuni sistemi di Help (specialmente WinHelp) funzionano associando 
numeri (conosciuti come ID di contesto) a parole chiave in un modo interno al 
sistema di Help e quindi non visibile all'applicazione. Tali sistemi richiedono che 
l'applicazione supporti l'Help in base al contesto, vale a dire l'applicazione richiama 
il sistema Help con quel contesto, invece che con una stringa, e il sistema di Help 
traduca tale numero. 

Le applicazioni scritte nella CLX e nella CLX possono dialogare con sistemi che 
richiedono un Help in base al contesto estendendo l'oggetto che implementa 
ICustomHelpViewer in modo che implementi anche lExtendedHelpViewer. 
lExtendedHelpViewer fornisce anche un supporto per dialogare con sistemi di Help 
che permettono di passare direttamente ad argomenti di livello piu alto invece di 
utilizzare ricerche per parole chiave. II visualizzatore natico WinHelp compie 
l'operazione automaticamente. 

lExtendedHelpViewer espone quattro funzioni. Due di esse - UnderstandsContext e 
DisplayHelpByContext - sono utilizzate per supportare gli Help in base al contesto; le 
altre due - Under stands! opic and DisplayTopic - sono utilizzate per supportare gli 
argomenti. 

Quando un utente dell'applicazione preme il tasto Fl, l'Help Manager chiama 

int__fastcall lExtendedHelpViewer: :UnderstandsContext (const int ContextID, AnsiStrmg 
HelpFileName) 

e il controllo attivato attualmente supporta un Help in base al contesto invece che 
basato su parola chiave. Come nel caso di ICustomHelpViewerr.ilnderstandsKeyword, 
l'Help Manager interroga in sequenza tutti i visualizzatori di Help registrati. A 
differenza del caso con ICustomHelpViewer::UnderstandsKeyword(), pero, se piu di un 
visualizzatore supporta un determinato contesto, viene attivato il primo 
visualizzatore registrato che supporta quel certo contesto. 

L'Help Manager chiama 

void__fastcall lExtendedHelpViewer: : DisplayHelpByContext (const int ContextID, AnsiString 
HelpFileName) 

dopo aver eseguito la scansione ciclica dei visualizzatori di Help registrati. 

Le funzioni per il supporto degli argomenti operano in modo analogo: 

bool__fastcall lExtendedHelpViewer: :UnderstandsTopic (const AnsiString Topic) 

viene utilizzata per eseguire la scansione ciclica dei visualizzatori di Help e chiedere 
se supportano un argomento; 

void__fastcall lExtendedHelpViewer: :DisplayTopic (const AnsiString Topic) 
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viene utilizzata per richiamare il primo visualizzatore registrato che riferisce di 
essere in grado di fornire l'aiuto per queH'argomento. 

Implementazione IHelpSelector 



IHelp ^Selector viene utilizzato in combinazione con ICustomHelpViewer. Quando 
esistono piu visualizzatori di Help che sostengono di essere in grado di fornire un 
supporto per una certa parola chiave, per un contesto o per un determinato 
argomento, o di essere in grado di fornire un indice, l'Help Manager deve effettuare 
una scelta. Nel caso di contesti o di argomenti, l'Help Manager seleziona sempre il 
primo visualizzatore di Help che sostiene di essere in grado di fornire il supporto. 
Nel caso delle parole chiave o dell'indice, per impostazione predefinita l'Help 
Manager selezionera il primo visualizzatore Help. Questo comportamento puo 
essere ridefinito da un'applicazione. 

Per ridefinire la decisione dell'Help Manager in questi casi, l'applicazione deve 
registrare una classe che fornisca un'implementazione dell'interfaccia 
IHelpSelector. IHelpSelector esporta due funzioni: SelectKeyword, e TableOf Contents. 
Entrambe accettano come argomento un TStrings contenente, ad uno ad uno, o le 
possibili corrispondenze con la parola chiave o i nomi dei visualizzatori che 
sostengono di essere in grado di fornire un indice. Chi implementa la funzione deve 
restituire l'indice (in TStringList) che rappresenta la stringa selezionata, TStringList 
viene quindi liberata dall'Help Manager. 

L'Help Manager potrebbe fare confusione se le stringhe vengono riorganizzate; si 
consiglia a chi implementa IHelpSelector di astenersi dal fare cio. II sistema di Help 
supporta un solo HelpSelector; quando si registrano nuovi selettori, qualsiasi selettore 
precedentemente esistente viene scollegato. 

Registrazione di oggetti di sistema di Help 



Affinche l'Help Manager possa comunicare con loro, gli oggetti che implementano 
ICustomHelpViewer, IExtendedHelpViewer, ISpecialWinHelp Viewer e IHelpSelector 
devono essere registrati con l'Help Manager. 

Per registrare con l'Help Manager oggetti di sistema di Help, e necessario: 

• Registrare il visualizzatore di Help. 

• Registrare il selettore di Help. 

Registrazione dei visualizzatori di Help 

La unit che contiene l'implementazione di oggetto deve utilizzare Helplntfs. Nel file 
header della unit che lo implementa si deve dichiarare un'istanza dell'oggetto. 

La unit implementante deve includere una direttiva di awio pragma che chiama un 
metodo che assegna la variabile di istanza e la passa alia funzione RegisterViewer. 
RegisterViewer e una funzione esportata da Helplntfs.pas che accetta come argomento 
uno ICustomHelpViewer e restituisce uno IHelpManager. Lo IHelpManager dovrebbe 
essere memorizzato per un successivo utilizzo. 
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II file .cpp corrispondente contiene il codice per registrare l'interfaccia. Per 
l'interfaccia descritta sopra, il codice di registrazione assomiglia al seguente: 

void InitServices ( ) 

{ 

THelpImplementor GlobalClass; 

Global = dynamic_cast<ICustomHelpViewer*> (GlobalClass ) ; 
Global->AddRef ; 

Helplntf s : : Regi st erVi ewer (Global, GlobalClass ->Manager) ; 

} 

tpragma startup InitServices 

L'oggetto Help Manager deve essere liberato nel distruttore dell'oggetto GlobalClass 
nel caso non sia stato gia liberato. 

Registrazione dei selettori di Help 

La unit che contiene 1'implementazione dell'oggetto deve utilizzare Forms nella VCL 
oppure QForms Nella CLX. Nel file .ccp dell'unit che lo implementa si deve 
dichiarare un'istanza dell'oggetto. 

La unit che lo implementa deve registrare il selettore di Help attraverso la proprieta 
HelpSystem dell'oggetto globale Application: 

Application->HelpSystem->AssignHelpSelector (myHelpSelectorlnstance) 

Questa procedura non restituisce un valore. 



Utilizzo dell'Help in un'applicazione VCL 



Le seguenti sezioni spiegano come utilizzare l'Help in un'applicazione VCL. 



• In che modo TApplication elabora l'Help VCL 

• In che modo i controlli VCL elaborano l'Help 

• Chiamata diretta a un sistema di Help 

• Utilizzo di IHelpSystem 

In che modo TApplication elabora l'Help VCL 



TApplication della VCL fornisce due metodi accessibili dal codice dell'applicazione: 
Tabella 7.5 Metodi Help in TApplication 



HelpCommand Accetta un HELP_COMMAND in stile Windows Help e lo passa a WinHelp. 

Le richieste di Help inviate attraverso questo meccanismo vengono passate 
solo alle implementazioni di IspecialWinHelp Viewer. 

HelpContext Richiama il sistema di Help con una richiesta di Help in base al contesto. 

Help Keyword Richiama il sistema di Help con una richiesta di Help in base a una parola 
chiave. 



Helpjump 



Richiede la visualizzazione di un particolare argomento. 
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Tutte e quattro le funzioni prendono i dati che vengono loro passati e li inoltrano 
tramite un membro dati di T Application che rappresenta il sistema di Help. Quel 
membro dati e direttamente accessibile attraverso la proprieta HelpSystem a sola 
lettura. 

In che modo i controlli VCL elaborano I'Help 



Tutti i controlli della VCL che derivano da TControl espongono diverse proprieta 
utilizzate dal sistema di Help: HelpType, HelpContext, e HelpKeyword. 

La proprieta HelpType contiene un'istanza di tipo enumerativo che determina se chi 
ha progettato il controllo si aspettava che l'aiuto fosse fornito in base a una parola 
chiave o in base al contesto. Se HelpType e impostata a htKeyword, il sistema Help si 
aspetta che il controllo utilizzi un help basato su parole chiave e quindi controller^ 
solo il contenuto della proprieta HelpKeyword. Al contrario, se HelpType e impostato a 
htContext, il sistema Help si aspetta che il controllo utilizzi un Help basato sul 
contesto e controllera solo il contenuto della proprieta HelpContext. 

Oltre alle proprieta, i controlli espongono un singolo metodo, InvokeHelp, che pud 
essere chiamato per passare una richiesta al sistema di Help. Tale metodo non 
richiede parametri e chiama i metodi nell'oggetto globale Application che 
corrispondono al tipo di help supportato dal controllo. 

I messaggi di help vengono richiamati automaticamente quando si preme Fl perche 
il metodo KeyDown di TWinControl richiama InvokeHelp. 

Utilizzo dell'Help in un'applicazione CLX 



Le seguenti sezioni spiegano come utilizzare I'Help in un'applicazione CLX. 

• In che modo TApplication elabora I'Help CLX 

• In che modo i controlli CLX elaborano I'Help 

• Chiamata diretta a un sistema di Help 

• Utilizzo di IHelpSystem 

In che modo TApplication elabora I'Help CLX 



TApplication della CLX fornisce due metodi accessibili dal codice dell'applicazione: 

• ContextHelp, che richiama il sistema di Help con una richiesta di Help in base al 
contesto 

• KeywordHelp, che richiama il sistema di Help con una richiesta di Help in base a 
una parola chiave 

Entrambe le funzioni accettano come argomento il contesto o la parola chiave che 
viene loro passato e inviano la richiesta attraverso un membro dati di TApplication, 
che rappresenta il sistema di Help. Quel membro dati e direttamente accessibile 
attraverso la proprieta HelpSystem sola lettura. 
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In che modo i controlli CLX elaborano I'Help 



Tutti i controlli che derivano da TControl espongono quattro proprieta utilizzate dal 
sistema di Help: HelpType, HelpFile, HelpContext, e HelpKeyword. HelpFile dovrebbe 
contenere il nome del file in cui e situato l'aiuto per il controllo; se l'aiuto e situato in 
un sistema di Help esterno che non ha bisogno di nomi di file (ad esempio, il sistema 
Man page), non si dovrebbe impostare un valore per la proprieta. 

La proprieta HelpType contiene un'istanza di tipo enumerativo che determina se chi 
ha progettato il controllo si aspettava che l'aiuto fosse fornito in base a una parola 
chiave o in base al contesto; le altre due proprieta sono collegate a quest'ultima. Se 
HelpType e impostata a htKeyword, il sistema Help si aspetta che il controllo utilizzi un 
help basato su parole chiave e quindi controllera solo il contenuto della proprieta 
HelpKeyword. Al contrario, se HelpType e impostato a htContext, il sistema Help si 
aspetta che il controllo utilizzi un Help basato sul contesto e controllera solo il 
contenuto della proprieta HelpContext. 

Oltre alle proprieta, i controlli espongono un singolo metodo, InvokeHelp, che puo 
essere chiamato per passare una richiesta al sistema di Help. Tale metodo non 
richiede parametri e chiama i metodi nell'oggetto globale Application che 
corrispondono al tipo di aiuto supportato dal controllo. 

I messaggi di aiuto vengono richiamati automaticamente quando si preme Fl perche 
il metodo KeyDown di TWidgetControl richiama InvokeHelp. 

Chiamata diretta a un sistema di Help 



Per ulteriori funzionalita di sistema di Help non fornite dalla VCL o dalla CLX, 
T Application fornisce una proprieta a sola lettura che consente di accedere 
direttamente al sistema di Help. Questa proprieta e un'istanza di 
un'implementazione dell'interfaccia IHelpSystem. IHelpSystem e IHelpManager sono 
implementati dallo stesso oggetto, ma un'interfaccia viene utilizzata per consentire 
all'applicazione di dialogare con I'Help Manager, mentre l'altra viene utilizzata per 
consentire ai visualizzatori di Help di dialogare con I'Help Manager. 

Utilizzo di IHelpSystem 



IHelpSystem permette alle applicazioni VCL o CLX di fare tre cose: 

• Fornisce all'Help Manager le informazioni sui percorsi. 

• Fornisce un nuovo selettore di Help. 

• Chiede all'Help Manager di visualizzare I'Help. 

L'assegnazione di un selettore di Help consente all'Help Manager di delegare il 
processo di decisione in quei casi in cui piu sistemi di Help esterni possono fornire 
un help per la stessa parola chiave. Per ulteriori informazioni, vedere la sezione 
"Implementazione IHelpSelector" on page 7-34. 
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Personalizzazione del sistema di Help dell'IDE 

IHelpSystem esporta quattro procedure e una funzione per richiedere all'Help 
Manager di visualizzare l'help: 

• ShowHelp 

• ShowContextHelp 

• ShowTopicHelp 

• ShowTableOf Contents 

• Hook 

Hook e destinata esclusivamente alia compatibilita con WinHelp e non dovrebbe 
essere utilizzata in un'applicazione CLX; permette l'elaborazione di messaggi 
WM_HELP che non possono essere mappati direttamente su richieste di Help basate 
su parola chiave, su contesto o su argomento. Ognuno degli altri metodi richiede due 
argomenti: la parola chiave, l'ID di contesto o l'argomento per cui si chiede aiuto e il 
file di Help in cui ci si aspetta di trovare l'aiuto. 

Di solito, a meno che non si stia richiedendo aiuto in base a un argomento, e 
ugualmente efficiente e molto piu chiaro passare le richieste di aiuto all'Help 
Manager tramite il metodo InvokeHelp del controllo. 

Personalizzazione del sistema di Help dell'IDE 



L'IDE di C++Builder supporta piu visualizzatori di Help utilizzando esattamente lo 
stesso meccanismo delle applicazioni VCL e CLX: delega le richieste di Help all'Help 
Manager, il quale le invia ai visualizzatori di Help registrati. L'IDE sfrutta il 
medesimo WinHelp Viewer utilizzato da VCL. 

Per installare nell'IDE un nuovo visualizzatore di Help, si fa esattamente cio che si 
farebbe in un'applicazione CLX, con una sola differenza. Si scrive un oggetto che 
implementa ICustomHelpViewer (e, se occorre, IExtendedHelpViewer) per inviare le 
richieste di Help al visualizzatore esterno preferito e si registra ICustomHelpViewer 
conl'IDE. 

Per registrare con l'IDE un visualizzatore custom di Help: 

1 Accertarsi che la unit che implementa il visualizzatore di Help contenga 
Helplntfs.cpp. 

2 Eseguire il build della unit in un package di progettazione registrato con l'IDE ed 
eseguire il build del package attivando l'opzione relativa ai package di esecuzione. 
(Questo e necessario per essere certi che l'istanza dell'Help Manager utilizzata 
dalla unit sia la stessa dell'istanza dell'Help Manager utilizzata dall'IDE.) 

3 Accertarsi che il visualizzatore di Help esista come istanza globale all'interno della 
unit. 

4 Nella funzione initialization bloccata da a #,pragma startup, accertarsi che 
l'istanza venga passata alia funzione RegisterHelpViewer. 
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Sviluppo dell'interfaccia utente 

dell'applicazione 

Quando si apre C++Builder o si crea un nuovo progetto, sullo schermo viene 
visualizzata una scheda vuota. Si progetta l'interfaccia utente di applicazione (UI) 
collocando e organizzando sulla scheda i componenti visuali, come finestre, menu e 
finestre di dialogo, prelevati dalla Component palette. 

Quando il componente visuale e sulla scheda, e possibile regolarne la posizione, le 
dimensioni e le altre proprieta regolabili in fase di progettazione e codificare i gestori 
di evento. C++Builder si occupa dei dettagli sottostanti della programmazione. 

Le seguenti sezioni descrivono alcune delle principali attivita sull'interfaccia, come le 
operazioni sulle schede, la creazione di modelli di componenti, l'aggiunta di finestre 
di dialogo e l'organizzazione di azioni per i menu e per le barre strumenti. 

Controllo del comportamento dell'applicazione 



T 'Application, TScreen e TForm sono classi the che costituiscono la struttura portante di 
tutte le applicazioni C++Builder e controllano il comportamento del progetto. La 
classe T Application costituisce la base di un'applicazione, in quanta fornisce le 
proprieta e i metodi che incapsulano il comportamento di un programma standard. 
TScreen viene usata in fase di esecuzione per tenere traccia delle schede e dei moduli 
dati che sono stati caricati, nonche delle informazioni specifiche di sistema, come la 
risoluzione delta schermo e i font video disponibili. Le istanze della classe TForm 
sono i blocchi per la costruzione dell'interfaccia utente dell'applicazione. Le finestre 
dell'applicazione, comprese quelle di dialogo, sono basate su TForm. 
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II lavoro a livedo di applicazione 



La variabile globale Application, di tipo T Application, si trova in ogni applicazione 
basata su VCL o su CLX. Application incapsula l'applicazione e fornisce molte 
funzioni che si verificano nel background del programma. Ad esempio, Application 
gestira il modo in cui viene chiamato un file Help dal menu del programma. La 
comprensione di come funziona 7 Application e molto importante per uno scrittore di 
componenti e per gli sviluppatori di applicazioni autonome; ma, quando si crea un 
progetto, e bene anche capire come impostare le opzioni che Application gestisce nella 
pagina Project I Options Application. 

Inoltre, Application riceve moltissimi eventi che si riferiscono all'intera applicazione. 
Ad esempio, l'evento OnActivate consente di eseguire azioni non appena si avvia 
l'applicazione, l'evento Onldle consente di eseguire processi in background quando 
l'applicazione non e occupata, l'evento OnMessage consente di intercettare i messagi 
di Windows (solo in ambiente Windows), l'evento OnEvent consente di intercettare 
gli eventi, e cosi via. Sebbene non sia possibile utilizzare 1'IDE per esaminare le 
proprieta e gli eventi della variabile globale Application, esiste un altro componente, 
TApplicationEvents, che intercetta gli eventi e consente di preparare i gestori di evento 
utilizzando 1'IDE. 

Gestione dello schermo 



Quando si crea un progetto, viene creata una variabile globale di tipo TScreen 
denominata Screen. Screen incapsula lo stato dello schermo sul quale viene eseguita 
l'applicazione. Le normali operazioni eseguite da Screen includono la specifica: 

• dell'aspetto del cursore. 

• delle dimensioni della finestra nella quale viene eseguita l'applicazione. 

• dell'elenco dei font disponibili per lo schermo. 

• il comportamento su piu schermi (solo Windows). 

Se l'applicazione Windows viene eseguita su piu monitor, Screen conserva l'elenco 
dei monitor e le loro dimensioni, in modo che si possa gestire efficacemente il layout 
dell'interfaccia utente. 

Se si utilizza CLX per programmi multipiataforma, il comportamento predefinito 
delle applicazioni e quello di creare un componente screen in base alle informazioni 
sul dispositivo video corrente e di assegnarlo a Screen. 

Impostazione delle schede 



TForm e la classe fondamentale per la creazione di applicazioni GUI. Quando si apre 
C++Builder e si visualizza un progetto predefinito o si crea un nuovo progetto, viene 
visualizzata automaticamente una scheda che consente di iniziare il progetto 
dell'interfaccia utente. 
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Impostazione delle schede 



La prima scheda creata e salvata in un progetto diventa, per impostazione 
predefinita, la scheda principale del progetto, ovvero la prima scheda creata in fase 
di esecuzione. Quando poi si aggiungono schede ai progetti, si puo decidere di 
designare un'altra scheda come scheda principale dell'applicazione. Inoltre, la 
specificazione di una scheda come principale e un modo facile per verificarla in fase 
di esecuzione, in quanto, a meno che non si cambia l'ordine di creazione della scheda, 
la scheda principale e la prima scheda visualizzata durante l'esecuzione 
dell'applicazione. 

Per cambiare la scheda principale del progetto: 

1 Scegliere Project I Options e selezionare la pagina Forms. 

2 Nella casella combinata Main Form selezionare la scheda che si vuole utilizzare 
come scheda principale del progetto e scegliere OK. 

A questo punto, se si esegue l'applicazione, verra visualizzata la scheda selezionata 
come scheda principale. 

Occultamento della scheda principale 



In fase di avvio dell'applicazione, e possibile fare in modo che la scheda principale 
non venga visualizzata. Per fare cio, occorre utilizzare la variabile globale Application 
(descritta nel paragrafo , "II lavoro a livello di applicazione", a pagina 8-2). 

Per nascondere la scheda principale in fase di avvio: 

1 Scegliere l'opzione Project I View Source per visualizzare il file principale del 
progetto. 

2 Aggiungere le seguenti righe di codice subito dopo la chiamata a Application- 

>CreateForm( ) e prima della chiamata a Application->Run( ) . 

Application->ShowMainForm = false; 

3 Usando l'Object Inspector, impostare la proprieta Visible della scheda principale a 
false. 

Aggiunta di schede 



Per aggiungere una scheda al progetto, occorre selezionare File I New I Form. E 
possibile vedere tutte le schede del progetto e le loro unit associate elencate nel 
Project Manager (View I Project Manager) e, scegliendo il comando View I Forms, e 
possibile visualizzare un elenco delle schede non associate. 

Collegamento delle schede 

Aggiungendo una scheda a un progetto, si aggiunge nel relativo file un riferimento al 
progetto, ma non alle altre unit del progetto. Prima di scrivere il codice che fa 
riferimento alia nuova scheda, occorre aggiungere un riferimento alia scheda stessa 
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nei file unit delle schede di referenziazione. Questa operazione viene detta 
collegamento delta scheda. 

Uno dei motivi piu comuni per collegare le schede e quello di fornire l'accesso ai 
relativi componenti. Per esempio, questo collegamento verra spesso usato per 
consentire a una scheda che contiene componenti associati ai dati di collegarsi ai 
componenti di accesso ai dati di un modulo dati. 

Per collegare una scheda a un'altra: 

1 Selezionare la scheda che ha bisogno di fare riferimento a un'altra scheda. 

2 Scegliere File I Include Unit Hdr. 

3 Selezionare il nome della unit della scheda a cui bisogna fare riferimento. 

4 Scegliere OK. 

Collegare una scheda a un'altra vuole dire che la unit della scheda contiene 1' 
intestazione per la unit della scheda dell'altra, owero che la scheda collegata e i suoi 
componenti sono nel campo d'azione della scheda collegante. 

Gestione del layout 



Nel caso piu semplice il layout dell'interfaccia utente viene controllato dal modo in 
cui i controlli vengono collocati nelle schede. Le scelte di collocazione effettuate 
vengono riflesse nelle proprieta Top, Left, Width, e Height del controllo. E possibile 
cambiare questi valori in fase di esecuzione per cambiare la posizione e le dimensioni 
dei controlli nelle schede. 

I controlli hanno, comunque, una grande quantita di altre proprieta che consentono 
loro di regolare automaticamente il loro contenuto o i loro contenitori. Cio consente 
di preparare le schede in modo che le diverse parti costituiscano un tutt'uno. 

Due proprieta incidono sul modo in cui un controllo viene posizionato e 
dimensionato rispetto al suo genitore. La proprieta Align permette di forzare un 
controllo per sistemarlo perfettamente all'interno del suo genitore lungo un 
determinato margine o riempiendo l'intera area client dopo uno dei controlli che 
sono stati allineati. Quando il genitore viene ridimensionato, i controlli ad esso 
allineati vengono ridimensionati automaticamente e rimangono posizionati in modo 
da adattarsi rispetto a un determinato margine. 

Se si vuole tenere un controllo posizionato su un particolare margine del suo 
genitore, senza che pero venga ridimensionato per essere sistemato lungo l'intero 
margine, basta usare la proprieta Anchors. 

Se si vuole avere la certezza che un controllo non diventi troppo grande o troppo 
piccolo, si puo ricorrere alia proprieta Constraints. Constraints permette di specificare 
l'altezza massima e minima, e la larghezza massima e minima del controllo. 
Impostando questi elementi, si limitano le dimensioni (in pixel) dell'altezza e della 
larghezza del controllo. Per esempio, impostando MinWidth e MinHeight dei vincoli 
su un oggetto contenitore, si puo garantire che gli oggetti figlio siano sempre visibili. 

II valore di Constraints si propaga attra verso la gerarchia genitore/ figlio, in modo che 
le dimensioni di un oggetto possano essere vincolate, dal momento che esso contiene 
oggetti figlio allineati soggetti al vincolo delle dimensioni. Constraints puo anche 
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impedire che un controllo venga ridotto rispetto a una certa dimensione quando 
viene chiamato il suo metodo ChangeScale. 

TControl introduce un evento protected, OnConstrainedResize, di tipo 
TConstrainedResizeEvent: 

void __fastcall (__closure *TConstramedResizeEvent) (System: :T0bject* Sender, int 
&MinWidth, int &MinHeight, int SMaxWidth, int &MaxHeight); 

Questo evento consente di ridefinire i vincoli delle dimensioni quando si cerca di 
ridimensionare il controllo. I valori dei vincoli vengono passati come parametri var 
che possono essere modificati all'interno del gestore di evento. I valori dei vincoli 
vengono passati come parametri varche possono essere modificati all'interno del 
gestore di evento. OnConstrainedResize e published per gli oggetti contenitore (TForm, 
TScrollBox, TControlBar e TPanel). Inoltre, gli scrittori di componenti possono usare o 
pubblicare questo evento per qualsiasi discendente di TControl. 

I controlli con un contenuto in grado di cambiare le dimensioni hanno una proprieta 
AutoSize, che obbliga il controllo a regolare le dimensioni in funzione degli oggetti 
contenuti. 

Uso delle schede 



Quando si crea una scheda dall'IDE, C++Builder crea automaticamente la scheda in 
memoria includendo il codice nel punto di ingresso principale della funzione 
dell'applicazione. Solitamente, questo e il comportamento desiderato e non occorre 
fare nulla per modificarlo. La finestra principale rimane, cioe, sullo schermo per tutta 
la durata del programma, e quindi probabilmente non sara necessario modificare il 
comportamento predefinito di C++Builder quando si crea la scheda per la finestra 
principale. 

Tuttavia, puo risultare inopportuno avere in memoria tutte le schede 
dell'applicazione per la durata dell'esecuzione del programma. Se, cioe, si preferisce 
che le finestre di dialogo dell'applicazione non stiano tutte in memoria 
contemporaneamente, e possibile creare dinamicamente le finestre di dialogo 
quando si vuole che vengano visualizzate. 

Le schede possono essere modali o non modali. Le schede modali sono schede con le 
quali l'utente deve interagire prima di passare a un'altra scheda (per esempio, una 
finestra di dialogo che richiede l'immissione dell'utente). Le schede non modali, 
invece, sono finestre che vengono visualizzate finche non vengono coperte da 
un'altra finestra o non vengono chiuse o ridotte a icona dall'utente. 

Controllo delle schede in memoria 



Per impostazione predefinita, C++Builder crea automaticamente in memoria la 
scheda principale dell'applicazione includendo il seguente codice nel punto 
d'ingresso principale dell'applicazione: 

Application ->CreateForm( classid(TForml) , &Forml); 
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Questa funzione crea una variabile globale con lo stesso nome della scheda. Quindi, 
ogni scheda contenuta in un'applicazione ha una variabile globale associata. Questa 
variabile e un puntatore a un'isianza della classe della scheda e viene usata per fare 
riferimento alia scheda mentre l'applicazione e in esecuzione. Ogni file di codice 
sorgente (.cpp) che include il file header (.h) della scheda puo accedere alia scheda 
tramite questa variabile. 

Poiche la scheda viene aggiunta nel punto d'ingresso principale dell'applicazione, la 
scheda appare non appena si avvia il programma e resta in memoria per tutta la 
durata dell'applicazione. 

Visualizzazione di una scheda creata automaticamente 

Se si sceglie di creare una scheda in fase di avvio, che si vuole visualizzare solo piu 
tardi durante l'esecuzione del programma, il gestore di evento della scheda usa il 
metodo ShowModal per visualizzare la scheda gia caricata memoria: 

void __fastcall TMainMForm: :FirstButtonClick(TObject *Sender) 

{ 

ResultsForm->ShowModal () ; 

} 

In questo caso, poiche la scheda e gia in memoria, non c'e alcuna necessita di crearne 
un'altra istanza o di distruggerla. 

Creazione dinamica delle schede 

E probabile che non si voglia che tutte le schede dell'applicazione stiano in memoria 
contemporaneamente. Per ridurre la quantita di memoria necessaria al momento del 
caricamento, puo essere opportuno creare alcune schede solo quando c'e bisogno di 
usarle. Per esempio, una finestra di dialogo ha bisogno di trovarsi in memoria solo 
durante il periodo in cui un utente la utilizza. 

Per creare una scheda in una fase diversa durante l'esecuzione usando l'IDE, occorre: 

1 Selezionare File I New Form dal menu principale per visualizzare la nuova scheda. 

2 Rimuovere la scheda dall'elenco Auto-create forms della pagina Project I Options I 
Forms. 

Questa operazione rimuove la chiamata alia scheda. In alternativa, si puo 
rimuovere manualmente la seguente riga dal punto d'ingresso principale del 
programma: 

Application->CreateForm(__classid(TResultsForm) , SResultsForm) ; 

3 Chiamare la scheda nel momento desiderato, usando il metodo Show della scheda, 
se essa e non modale, o il metodo ShowModal, se e modale. 

Un gestore di evento per la scheda principale deve creare un'istanza della scheda 
risultato e distruggerla. Un modo per chiamare la scheda risultato consiste nell'usare 
la variabile globale nel modo seguente. Si noti che ResultsForm e una scheda modale, 
quindi il gestore usa il metodo ShowModal. 

void __fastcall TMainMForm: :FirstButtonClick(TObject *Sender) 

{ 
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ResultsForm = new TResultsForm(this) ; 
ResultsForm->ShowModal ( ) ; 
delete ResultsForm; 

} 

II gestore di evento dell'esempio cancella la scheda dopo averla chiusa, in modo che 
non occorrera ricrearla se occorrera usare ResultsForm in qualche altro punto 
dell'applicazione. Se la scheda fosse visualizzata usando Show, non potrebbe essere 
cancellata all'interno del gestore di evento, perche Show termina mentre la scheda e 
ancora aperta. 

Se si crea una scheda usando l'operatore new, bisogna ricordarsi di controllare che 
non sia nell'elenco Auto-create forms della pagina Project Options I Forms. Nello 
specifico, se la nuova scheda viene creata senza cancellare la scheda omonima 
dall'elenco, C++Builder crea la scheda in fase di avvio e questo gestore di evento crea 
una nuova istanza della scheda, sovrascrivendo il riferimento all'istanza creata 
automaticamente. Questa istanza esiste ancora, ma l'applicazione non puo piu 
accedervi. Dopo che il gestore di evento ha terminato l'esecuzione, la variabile 
globale non punta piu a una scheda valida. Qualsiasi tentativo di dereferenziare la 
variabile globale blocchera probabilmente l'applicazione. 

Creazione di schede non modali come finestre 

Occorre garantire che le variabili di riferimento per le schede non modali esistano 
finche la scheda e in uso. Questo vuol dire che queste variabili devono avere un 
campo d'azione globale. Nella maggior parte dei casi si usa la variabile globale di 
riferimento creata insieme alia scheda (il nome della variabile che corrisponde alia 
proprieta name della scheda). Se V applicazione richiede altre istanze della scheda, 
occorre dichiarare variabili globali distinte (di tipo puntatore alia classe form) una 
per ciascuna istanza. 

Creazione di un'istanza di scheda mediante una variabile locale 

Un modo piu sicuro per creare un'istanza univoca di una scheda module consiste 
nell'usare una variabile locale nel gestore di evento come riferimento a una nuova 
istanza. Se si usa una variabile locale, non importa se ResultsForm e stata creata 
automaticamente o meno. II codice nel gestore di evento non fa alcun riferimento alia 
variabile globale della scheda. Per esempio: 

void __fastcall TMainMForm: :FirstButtonClick(TObject *Sender) 

{ 

TResultsForm *rf = new TResultsForm(this ) ; // rf is local form instance 
rf->ShowModal () ; 

delete rf; // form safely destroyed 

} 

Si noti che l'istanza globale della scheda non viene mai usata in questa versione del 
gestore di evento. 

Normalmente, le applicazioni usano le istanze globali delle schede. Tuttavia, se 
occorre una nuova istanza di una scheda modale, e si usa quella scheda in una 
sezione limitata dell'applicazione, come una singola funzione, un'istanza locale e 
solitamente il modo piu sicuro ed efficace per lavorare con la scheda. 
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Naturalmente, non e possibile usare le variabili locali nei gestori di evento per le 
schede non modali, perche devono avere un campo d'azione globale per garantire 
che le schede esistano finche sono utilizzate. Show termina non appena si apre la 
scheda, quindi se e stata usata una variabile locale, questa variabile uscira 
immediatamente dal campo d'azione. 

Passaggio di altri argomenti alle schede 



Normalmente, le schede per l'applicazione vengono create dall'interno dell'IDE. 
Quando vengono create in questo modo, le schede hanno un costruttore che accetta 
un argomento, Owner, che e il proprietario della scheda da creare. (II proprietario e 
l'oggetto applicazione o scheda chiamante). Owner puo essere NULL. 

Per passare alia scheda altri argomenti, si deve creare un altro costruttore e istanziare 
la scheda usando 1' operatore new. La classe della scheda di esempio sotto riportata 
mostra un costruttore aggiuntivo, con un ulteriore argomento whichButton. Questo 
nuovo costruttore viene aggiunto manualmente alia classe della scheda. 

class TResultsForm : public TForm 

{ 

__published : // IDE-managed Components 
TLabel *ResultsLabel; 
TButton *OKButton; 

void __fastcall OKButtonClick(TObject *Sender) ; 
private: // User declarations 

public: // User declarations 

virtual fastcall TResultsForm(TComponent* Owner); 

virtual __fastcall TResultsForm(int whichButton, TComponent* Owner); 

}; 

Ecco il costruttore codificato manualmente che passa l'ulteriore argomento, 
whichButton. Questo costruttore usa il parametro whichButton per impostare la 
proprieta Caption di un controllo Label sulla scheda. 

void fastcall TResultsForm: :TResultsForm(int whichButton, TComponent* Owner) 

: TForm (Owner) 

{ 

switch (whichButton) { 
case 1: 

ResultsLabel->Caption = "You picked the first button!"; 
break ; 
case 2: 

ResultsLabel->Caption = "You picked the second button!"; 
break ; 
case 3 : 

ResultsLabel->Caption = "You picked the third button!"; 

} 

} 

Quando si crea un'istanza di una scheda con piu costruttori e possibile selezionare il 
costruttore piu adatto alio scopo. Per esempio, il seguente gestore OnClick per un 
pulsante su una scheda crea un'istanza di TResultsForm, che usa il parametro 
ulteriore: 
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void __fastcall TMainMForm: :SecondButtonClick(TObject *Sender) 

{ 

TResultsForm *rf = new TResultsForm(2, this); 
rf->ShowModal ( ) ; 
delete rf; 

} 

Recupero dei dati dalle schede 



La maggior parte delle applicazioni vere e proprie e costituita da piu schede. Spesso, 
occorre passare le informazioni tra queste schede. Le informazioni possono essere 
passate a una scheda per mezzo di parametri al costruttore della scheda ricevente, o 
assegnando i valori alle proprieta della scheda. II modo in cui si ottengono 
informazioni da una scheda dipende dal fatto che la scheda sia modale o non modale. 

Recupero dei dati da schede non modali 

E possibile estrarre con facilita informazioni dalle schede non modali chiamando 
funzioni membro public della scheda o sottoponendo a query le proprieta della 
scheda. Per esempio, si supponga che un'applicazione contenga una scheda non 
modale di nome ColorForm, che contiene una casella di riepilogo chiamata 
ColorListBox con un elenco di colori ("Red", "Green", "Blue", e cosi via). La stringa 
del nome del colore selezionato in ColorListBox viene memorizzata automaticamente 
in una proprieta di nome CurrentColor ogni volta che un utente seleziona un nuovo 
colore. La dichiarazione di classe per la scheda e la seguente: 

class TColorForm : public TForm 

{ 

__published : // IDE-managed Components 
TListBox "ColorListBox; 

void __fastcall ColorListBoxClick (TObject *Sender); 
private: // User declarations 

String getColorO ; 

void setColor (String) ; 

String curColor; 
public: // User declarations 

virtual fastcall TColorForm(TComponent* Owner); 

__property String CurrentColor = {read=getColor, write=setColor} ; 

}; 

II gestore di evento OnClick per la casella di riepilogo, ColorListBoxClick, imposta il 
valore della proprieta CurrentColor ogni volta che viene selezionato un nuovo 
elemento nella casella di riepilogo. II gestore di evento acquisisce la stringa dalla 
casella di riepilogo contenente il nome del colore e la assegna a CurrentColor. La 
proprieta CurrentColor usa la funzione setter, setColor, per memorizzare il valore 
effettivo per la proprieta nel membro dati private curColor: 

void __fastcall TColorForm: : ColorListBoxClick (TObject *Sender) 

{ 

int index = ColorListBox->ItemIndex; 
if (index >= 0) {// make sure a color is selected 
CurrentColor = ColorListBox->Items->Strings [index] ; 

} 
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else // no color selected 

CurrentColor = " " ; 

} 

// 

void TColorForm: :setColor(String s) 

{ 

curColor = s; 

} 

A questo punto, si supponga che un'altra scheda all'interno dell'applicazione, 
chiamata ResultsForm, debba scoprire quale colore e al momento selezionato su 
ColorForm ogni volta che si fa clic su un pulsante (chiamato UpdateButton) di 
ResultsForm. II gestore di evento OnClick per UpdateButton potrebbe avere il seguente 
formato: 

void __fastcall TResultsForm: :UpdateButtonClick(TObject *Sender) 

{ 

if (ColorForm) {// verify ColorForm exists 
String s = ColorForm->CurrentColor; 
//do something with the color name string 

} 

} 

Per prima cosa il gestore di evento verifica che ColorForm esista controllando se il 
puntatore e NULL. Quindi, riceve il valore della proprieta CurrentColor di ColorForm. 
La richiesta del CurrentColor chiama la sua funzione getter getColor mostrata di 
seguito: 

String TColorForm: :getColor ( ) 

{ 

return curColor; 

} 

In caso contrario, se la funzione getColor di ColorForm fosse pubblica, un'altra scheda 
potrebbe acquisire il colore attivo senza usare la proprieta CurrentColor (per esempio, 
String s = ColorForm->getColor()^. Infatti, non esiste un modo per impedire che 
un'altra scheda riceva il colore di ColorForm al momento selezionato contrassegnando 
direttamente le selezione della casella di riepilogo: 

String s = ColorListBox->Items->Strings [ColorListBox->ItemIndex] ; 

Tuttavia, l'uso di una proprieta rende l'interfaccia per ColorForm molto chiara e 
semplice. Tutto cio che una scheda ha bisogno di sapere su ColorForm e come 
controllare il valore di CurrentColor. 

Recupero dei dati da schede modali 

A differenza delle schede non modali, spesso le schede modali contengono le 
informazioni necessarie per altre schede. L'esempio piu comune e una scheda A che 
lancia una scheda modale B. Quando la scheda B viene chiusa, la scheda A ha 
bisogno di conoscere che cosa ha fatto l'utente con la scheda B per decidere come 
procedere con l'elaborazione della scheda A. Se la scheda B e ancora in memoria, puo 
essere sottoposta a query tramite proprieta o funzioni membro esattamente come 
nell'esempio sulle schede non modali sopra riportato. Ma come gestire le situazioni 
in cui la scheda B viene cancellata dalla memoria alia chiusura? Poiche una scheda 
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non ha una valore di ritorno esplicito, occorre preservare le informazioni importanti 
della scheda prima che venga distrutta. 

Per illustrare cio, si prendera ora in considerazione una versione modificata della 
scheda ColorForm che e progettata per essere una scheda modale. La dichiarazione di 
classe e la seguente: 

class TColorForm : public TForm 
{ 

published : // IDE-managed Components 

TListBox *ColorListBox; 
TButton *SelectButton; 
TButton *CancelButton; 

void __fastcall CancelButtonClick(TObject * Sender ) ; 

void __fastcall SelectButtonClick(TObject *Sender); 
private: // User declarations 

String* curColor; 
public: // User declarations 

virtual fastcall TColorForm(TComponent* Owner); 

virtual fastcall TColorFormfString* s, TComponent* Owner); 

}; 

La scheda ha una casella di riepilogo chiamata ColorListBox con un elenco di nomi di 
colori. Quando viene premuto, il pulsante di nome SelectButton prende nota del nome 
del colore attualmente selezionato in ColorListBox e chiude la scheda. CancelButton e 
un pulsante che chiude semplicemente la scheda. 

Si noti che e stato aggiunto un costruttore definito dall'utente alia classe che accetta 
un argomento String*. Presumibilmente, questo String* punta a una stringa che 
indica la scheda che lancia ColorForm. L'implementazione di questo costruttore e la 
seguente: 

void fastcall TColorForm: :TColorForm(String* s, TComponent* Owner) 

: TForm (Owner) 

{ 

curColor = s; 
*curColor = ""; 

} 

II costruttore salva il puntatore in un membro dati privato curColor e inizializza la 
stringa a una stringa vuota. 

Per usare il costruttore definito dall'utente sopra riportato, la scheda deve essere 
creata esplicitamente. Essa non puo essere creata automaticamente quando 
l'applicazione e awiata. Per informazioni dettagliate, consultare il paragrafo 
"Controllo delle schede in memoria" a pagina 8-5. 

Nell'applicazione, l'utente seleziona un colore dalla casella di riepilogo e preme 
SelectButton per salvare la scelta e chiudere la scheda. II gestore di evento OnClick per 
SelectButton potrebbe avere questa forma: 

void __fastcall TColorForm: :SelectButtonClick(TObject *Sender) 
{ 

int index = ColorListBox->ItemIndex; 
if (index >= 0) 

*curColor = ColorListBox->Items->Strings [index] ; 
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Closed ; 

} 

Notare che il gestore di evento memorizza il nome del colore selezionato nella stringa 
address che e stata passata al costruttore. 

Per usare efficacemente ColorForm, la scheda chiamante deve passare il costruttore a 
un puntatore a una stringa esistente. Per esempio, si supponga che ColorForm e stata 
istanziata da una scheda chiamata ResultsForm in risposta a un clic su un pulsante 
chiamato UpdateButton di ResultsForm. II gestore di evento dovrebbe essere simile al 
seguente codice: 

void __fastcall TResultsForm: :UpdateButtonClick(TObject *Sender) 

{ 

String s; 
GetColor(&s) ; 
if (s != "") { 

//do something with the color name string 

} 

else { 

// do something else because no color was picked 

} 

} 

// 

void TResultsForm: :GetColor (String *s) 
{ 

ColorForm = new TColorForm(s, this); 
ColorForm->ShowModal ( ) ; 
delete ColorForm; 

ColorForm = 0; // NULL the pointer 

} 

UpdateButtonClick crea una stringa chiamata s. L'indirizzo di s viene passato alia 
funzione GetColor che crea ColorForm, passando il puntatore a s come argomento per 
il costruttore. ColorForm viene cancellata non appena viene chiusa, ma il nome del 
colore che e stato selezionato e ancora protetto in s, presupponendo che e stato 
selezionato un colore. Altrimenti, s contiene una stringa vuota che una chiara 
indicazione che l'utente e uscito da ColorForm senza selezionare un colore. 

Questo esempio usa una variabile string per contenere informazioni dalla scheda 
modale. Naturalmente, possono essere usati oggetti piu complessi a seconda delle 
necessita. Tenere ben presente che occorre sempre fornire un modo per consentire 
alia scheda chiamante di sapere se la scheda modale e stata chiusa senza apportare 
modifiche o effettuare selezioni (con s impostato, per impostazione predefinita, a una 
stringa vuota). 

Riutilizzo di componenti e gruppi di componenti 



C++Builder offre molti modi per salvare e riutilizzare il lavoro fatto con i 
componenti: 
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• L'uso di modelli di componenti rappresenta un modo semplice e veloce per 
configurare e salvare gruppi di componenti. Consultare il paragrafo "Creazione e 
utilizzo di modelli di componenti" a pagina 8-13. 

• Nel Repository e possibile salvare schede, moduli dati e progetti. In questo modo si 
dispone di un database centrale di elementi riutilizzabili ed e possibile usare 
l'ereditarieta delle schede per propagare le modifiche. 

• E possibile salvare i frame nel Repository o nella Component palette. I frame 
utilizzano l'ereditarieta delle schede e possono essere incorporati nelle schede o in 
altri frame. Consultare il paragrafo "Operazioni con i frame" a pagina 8-14. 

• La creazione di componenti custom e il sistema piu complicato per riutilizzare il 
codice, ma offre una maggiore flessibilita. Consultare il Capitolo 45, "Introduzione 
alia creazione di componenti". 

Creazione e utilizzo di modelli di componenti 



E possibile creare modelli costituiti da uno o piu componenti. Dopo aver disposto dei 
componenti su una scheda, impostato le rispettive proprieta e aver scritto il codice 
relativo, li si puo salvare come un modello di componente. In seguito, selezionando il 
modello dalla Component palette, e possibile collocare su una scheda i componenti 
prestabiliti con una sola operazione; tutte le proprieta associate e il codice di gestione 
degli eventi vengono aggiunti contemporaneamente al progetto. 

Una volta collocato un modello su una scheda, e possibile riposizionare i componenti 
in modo indipendente, azzerare le proprieta, e creare o modificare i gestori di evento 
esattamente come se si fosse collocato ciascun componente con un'operazione 
separata. 

Per creare un modello di componente: 

1 Collocare e disporre dei componenti su una scheda. Nell'Object Inspector, 
impostarne le proprieta e gli eventi come si desidera. 

2 Selezionare i componenti. II modo piu semplice per selezionare molti componenti 
consiste nel trascinare il mouse su tutti i componenti. Agli vertici di ciascun 
componente selezionato appariranno delle maniglie di color grigio. 

3 Scegliere il comando Component I Create Component Template. 

4 Specificare nella casella di testo Component Template Information un nome da 
assegnare al modello di componente. La proposta predefinita e il tipo componente 
del primo componente selezionato al punto 2, seguito dalla parola "Template". Ad 
esempio, se si seleziona un'etichetta e quindi una casella di modifica, il nome 
proposto sara "TLabelTemplate". E possibile modificare questo nome, ma fare 
attenzione a non duplicare nomi di componenti esistenti. 

5 Nella casella di testo Palette page, specificare la pagina della Component palette in 
cui si desidera collocare il modello. Se si specifica una pagina inesistente, nel 
momento in cui si salvera il modello verra creata una nuova pagina. 

6 Sotto Palette Icon, selezionare una bitmap che servira a rappresentare il modello 
sulla tavolozza. La bitmap proposta per impostazione predefinita sara la bitmap 
utilizzata dal tipo di componente del primo componente selezionato al punto 2. 



Sviluppo dell'interfaccia utente dell'applicazione 8-13 



Operazioni con i frame 

Per cercare altre bitmap, fare clic su Change. La bitmap selezionata non deve 
essere piu grande di 24 pixel per 24 pixel. 

7 Fare click su OK. 

Per rimuovere i modelli dalla Component palette, scegliere il comando Component I 
Configure Palette. 

Operazioni con i frame 



Un frame (TFrame), analogamente a una scheda, e un contenitore per altri 
componenti. Esso utilizza lo stesso meccanismo di possesso delle schede per 
l'istanzazione e la distruzione dei componenti in esso presenti, e le stessa relazioni 
genitore-figlio per la sincronizzazione delle proprieta dei componenti. 

Per certi versi, un frame e piu simile a un componente custom che a una scheda. Una 
volta creato e salvato un frame, esso continua a funzionare come una unit, ereditando 
le modifiche dai componenti (inclusi altri frame) in esso contenuti. Una volta creato e 
salvato un frame, esso continua a funzionare come una unit, ereditando le modifiche 
dai componenti (inclusi altri frame) in esso contenuti. Quando si include un frame in 
un'altro frame o in una scheda, esso continua ad ereditare le modifiche apportate al 
frame da cui e stato derivato. 

I frame sono utili per organizzare gruppi di controlli che vengono utilizzati in piu 
punti dell'applicazione. Ad esempio, se si ha una bitmap che viene utilizzata su piu 
schede, e possibile collocarla in un frame e solo una copia di quella bitmap verra 
inclusa nelle risorse dell'applicazione. Si potrebbe anche includere in un frame una 
serie di campi di editing, il cui scopo e quello di consentire l'editing di una tabella, e 
utilizzare quel frame ogni volta che si desidera inserire dati nella tabella. 

Creazione di frame 



Per creare un frame vuoto, scegliere il comando File I New I Frame oppure scegliere 
File I New I Other e fare doppio clic su Frame. A questo punto e possibile trascinare 
sul nuovo frame altri componenti (inclusi altri frame. 

Di solito e buona norma-anche se non strettamente necessario-salvare i frame come 
parte di un progetto. Se si vuole creare un progetto che contenga solo frame e 
nessuna scheda, scegliere il comando File I New I Application, chiudere la nuova 
scheda e la unit senza salvarle, quindi scegliere il comando File I New I Frame e 
salvare il progetto. 

Quando si salvano i frame, e bene evitare l'uso dei nomi predefiniti, quali Unitl, 
Project! e cosi via, in quanto molto probabilmente provocheranno conflitti quando si 
cerchera di utilizzare il frame in un secondo tempo. 

In fase di progetto, e possibile visualizzare tutti i frame inclusi nel progetto corrente 
scegliendo il comando View I Forms e selezionando un frame. Come con le schede e i 
moduli dati, e possibile passare dalla visualizzazione grafica nel Form Designer al 
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file .form del frame, e viceversa, facendo clic destro e scegliendo il comando View as 
Form oppure View as Text. 

Aggiunta di frame alia Component palette 



I frame vengono aggiunti alia Component palette come modelli di componenti. Per 
aggiungere un frame alia Component palette, aprire il frame nel Form Designer (a 
questo scopo non e possibile utilizzare un frame incluso in un altro componente), fare 
clic destro sul frame e scegliere il comando Add della Palette. Nella finestra di 
dialogo Component Template Information che si aprira, selezionare un nome, la 
pagina della tavolozza e l'icona da assegnare al nuovo modello. 

Uso e modifica di frame 



Per utilizzare un frame in un'applicazione, e necessario collocarlo, direttamente o 
indirettamente, su una scheda. E possibile aggiungere frame direttamente alle 
schede, ad altri frame o ad altri oggetti contenitore come i pannelli e le caselle a 
scorrimento. 

Form Designer consente di aggiungere un frame a un'applicazione in due modi: 

• Selezionare un frame nella Component palette e trascinarlo su una scheda, su un 
altro frame o su un altro oggetto contenitore. Se occorre, Form Designer chiede il 
permesso di includere il file unit del frame nel progetto. 

• Selezionare Frames dalla pagina Standard della Component palette e fare clic su 
una scheda o su un altro frame. Apparira una finestra di dialogo con l'elenco dei 
frame che sono gia stati inclusi nel progetto; selezioanrne uno e fare clic su OK. 

Quando si trascina un frame su una scheda o su un altro contenitore, C++Builder 
dichiara una nuova classe che deriva dal frame selezionato. (In modo analogo, 
quando si aggiunge una nuova scheda a un progetto, C++Builder dichiara una nuova 
classe che deriva da TForm.) Cio significa che le modifiche fatte successivamente al 
frame originale (l'antenato) si propagano al frame incorporato, mentre le modifiche 
apportate al frame incorporato non si propagano a ritroso all'antenato. 

Si supponga, ad esempio, di voler assemblare un gruppo di componenti per l'acecsso 
ai dati e di controlli data-aware da utilizzare piu volte, anche in piu di una 
applicazione. Uno dei modi per fare cio potrebbe essere quello di raccogliere i 
componenti in un modello di componenti; ma, se si iniziasse ad usare il modello e poi 
si cambiasse idea rispetto alia disposizione dei controlli, si dovrebbe tornare indietro 
e modificare manualmente tutti i progetti in cui e stato collocato il modello. 

Invece, se si collocassero i componenti database in un frame, le eventuali modifiche 
dovrebbero essere apportate in un solo posto; le modifiche al frame originale si 
propagano ai discendenti in esso contenuti al momento della ricompilazione del 
progetto. Alio stesso tempo, si e liberi di modificare qualunque frame incluso senza 
toccare il frame originale o altri suoi discendenti incorporati. L'unica limitazione 
nella modifica di frame incorporati consiste nel non poter aggiungere ad essi altri 
componenti. 
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Figura 8.1 Un frame con controlli data-aware e un componente datasource 
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Oltre a sempliifcare la manutenzione, i frame risultano utili nell'utilizzare le risorse 
in modo piu efficiente. Ad esempio, per utilizzare in una applicazione una bitmap o 
un'altra immagine grafica, si dovrebbe caricare l'immagine grafica nella proprieta 
Picture di un controllo TImage. Se nell'applicazione la stessa immagine viene 
utilizzata piu volte, ciuscun oggetto Image collocato su una scheda provochera 
l'aggiunta al file di risorse della scheda di un'altra copia dell'immagine. (Questo e 
vero anche se si imposta TImage::Picture una volta per tutte e si salva il controllo 
Image come modello di componente). La soluzione migliore consiste nel trascinare un 
oggetto Image su un frame, caricarvi l'immagine grafica e quindi usare il frame nel 
punto in cui si vuole far apparire l'immagine. In questo modo i file scheda prodotti 
risultano piu piccoli oltre ad offrire la possibility di cambiare globalmente 
l'immagine utilizzata, semplicemente modificando la proprieta Image sul frame 
originale. 

Condivisione di frame 



E possibile condividere un frame con altri sviluppatori in due modi: 

• Aggiungendo il frame all' Object Repository. 

• Distribuendo i file unit (.cpp e h.) e i file scheda (.dfm o .xfm). 

Per aggiungere un frame al Repository, aprire un qualsiasi progetto contenente il 
frame, fare clic destro in Form Designer e scegliere il comando Add to Repository. 
Per maggiori informazioni, consultare "Utilizzo dell'Object Repository" a 
pagina 7-25. 

Se si distribuiscono i file unit e scheda ad altri sviluppatori, essi potranno aprirli e 
aggiungerli alia Component palette. Se il frame incorpora altri frame dovranno aprire 
il frame come parte di un progetto. 



Sviluppo di finestre di dialogo 



I componenti finestra di dialogo della pagina Dialogs della Component palette 
rendono disponibili alle applicazioni diverse finestre di dialogo. Queste finestre di 
dialogo forniscono alle applicazioni un'interfaccia familiare e uniforme e permettono 
all'utente di eseguire le comuni operazioni sui file, come l'apertura e il salvataggio di 
file. Le finestre di dialogo servono per visualizzare e/o ottenere dati. 
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Ogni finestra di dialogo si apre quando viene chiamato il metodo Execute. Execute 
restituisce un valore Boolean: se l'utente sceglie OK per accettare le modifiche 
apportate nella finestra di dialogo, Execute restituisce true; se l'utente sceglie Cancel 
per uscire dalla finestra di dialogo senza fare modifiche oppure senza salvarle, 
Execute restituisce false. 

Se si stanno sviluppando applicazioni multipiattaforma, e possibile utilizzare le 
finestre di dialogo fornite con CLX nella unit QDialogs. Per i sistemi operativi che 
hanno tipi di finestra di dialogo native per le comuni attivita, come l'apertura o il 
salvataggio dei file oppure per la modifica di font o colore, e possibile utilizzare la 
proprieta UseNativeDialog . Impostare UseNativeDialog a true se l'applicazione sara 
eseguira in tale ambiente e se si desidera che utilizzi le finestre di dialogo native 
invece delle finestre di dialogo Qt. 

Utilizzo delle finestre di dialogo di tipo Open 



Uno dei componenti finestra di dialogo piu comunemente utilizzato e TOpenDialog. 
Questo componente di solito viene richiamato da una voce di menu New o Open 
inclusa nel menu File della barra del menu principale di una scheda. La finestra di 
dialogo contiene diversi controlli che consentono di selezionare gruppi di file 
utilizzando i carattere jolly e di spostarsi nella struttura delle directory. 

II componente TOpenDialog rende disponibile all'applicazione una finestra di dialogo 
Open. Lo scopo di questa finestra di dialogo e quello di consentire che un utente 
selezioni un file da aprire. Per visualizzare la finestra di dialogo si utilizza il metodo 

Execute. 

Se l'utente sceglie OK nella finestra di dialogo, il file selezionato dall'utente viene 
memorizzato nella proprieta FileName di TOpenDialog, e lo si potra elaborare quindi 
a proprio piacimento. 

II frammento di codice seguente puo essere collocato in un Action e collegato alia 
proprieta Action di un sottoelemento di TMainMenu oppure collocato nell'evento 
OnClick del sottoelemento: 

if (OpenDialogl->Execute ( ) ) { 

filename = OpenDialogl->FileName; 

}; 

Questo codice visualizzera la finestra di dialogo e se l'utente preme il pulsante OK, 
copiera il nome del file in una variabile di tipo AnsiString, dichiarata in precedenza, 
di nome filename. 

Organizzazione delle azioni per barre e menu 



C++Builder dispone di numerose funzioni che semplificano la creazione, la 
personalizzazione e la gestione dei menu e delle barre strumenti. Queste funzioni 
permettono di organizzare liste di azioni che possono essere awiate dagli utenti 
dell'applicazione mediante la pressione di un pulsante su una barra strumenti, 
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scegliendo un comando di un menu oppure puntando un'icona e facendo clic su di 
essa. 

Spesso un insieme di azioni viene utilizzato da piu elementi dell'interfaccia utente. 
Ad esempio, i comandi Cut, Copy e Paste spesso vengono visualizzati sia in un menu 
Edit sia in una barra strumenti. Per utilizzare l'azione in piu elementi dell'interfaccia 
utente dell'applicazione e sufficiente aggiungere l'azione una sola volta. 

Per la piattaforma Windows, sono disponibili una serie di strumenti per semplificare 
la definizione e il raggruppamento di azioni, la creazione di layout differenti e la 
personalizzazone di menu in progettazione o in esecuzione. Questi strumenti sono 
noti con il nome collettivo di ActionBand, e i menu e le barre strumenti che con essi si 
creano vengono definiti bande di azioni. Di solito, e possibile creare un'interfaccia 
utente ActionBand come segue: 

• Creare la lista di azioni per creare un insieme di azioni che sara disponibile per 
l'applicazione (utilizzare 1' Action Manager, TActionManager) 

• Aggiungere all'applicazione gli elementi dell'interfaccia utente (utilizzare 
componenti ActionBand come TActionMainMenuBar e TActionToolBar) 

• Trascinare e rilasciare le azioni dall' Action Manager sugli elementi dell'interfaccia 
utente 

La tabella seguente definisce la terminologia relativa alia configurazione dei menu e 
delle barre strumenti: 



Tabella 8.1 Terminologia per la configurazione delle azioni 



Azione 



Banda di azioni 



Categoria di azioni 



Classi di azioni 



Client dell'azione 



Una risposta a qualcosa fatto dall'utente, come il clic su una voce di menu. 
Molte azioni standard, necessarie con una certa frequenza, sono gia 
disponibili e utilizzabili nelle applicazioni cosi come sono. Ad esempio, le 
operazioni sui file, come File Open, File SaveAs, File Run e File Exit, sono 
gia incluse, insieme a molte altre per l'editing, la formattazione, la ricerca, 
l'attivazione dell'help, per le finestre di dialogo e per le azioni di finestra. 
Utilizzando liste di azioni e V Action Manager e possibile anche 
programmare azioni custom e accedervi. 

Un contenitore per un insieme di azioni associate a un menu o a una barra 
strumenti personalizzabile. I componenti ActionBand per i menu 
principali e per le barre strumenti (TActionMainMenuBar e 
TActionToolBar) sono esempi di bande di azioni. 

Consente di raggruppare azioni e rilasciarle come gruppo su un menu o 
su una barra strumenti. Ad esempio, una delle categorie di azione 
standard e Search che include le azioni Find, FindFirst, FindNext e 
Replace. 

Classi che eseguono le azioni utilizzate nell'applicazione. Tutte le azioni 
standard sono definite in classi di azioni come TEditCopy, TEditCut e 
TEditUndo. E possibile utilizzare queste classi trascinandole dalla finestra 
di dialogo Customize e rilasciandole su una banda di azioni. 

Molto spesso rappresenta una voce di menu o un pulsante che riceve una 
notifica per avviare un'azione. Quando il client riceve un comando 
dell'utente (come il clic del mouse), avvia un'azione associata. 
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Tabella 8.1 Terminologia per la configurazione delle azioni 
Termine Definizione 

Lista di azioni Gestisce una lista di azioni che l'applicazione pud eseguire in risposta a 

qualcosa fatto dall'utente. 

Action Manager Raggruppa e organizza insiemi logici di azioni che possono essere 

riutilizzati su componenti ActionBand. Consultare TActionManager. 

Menu Elenca i comandi che l'utente dell'applicazione puo eseguire facendo clic 

su di essi. E possibile creare menu utilizzando la classe di menu 
ActionBand TActionMainMenuBar oppure utilizzando componenti 
multipiattaforma come TMainMenu o TPopupMenu. 

Destinazione Rappresenta l'elemento su cui un'azione esegue una certa cosa. Di solito 

la destinazione e un controllo, come un campo memo o un controllo dati. 
Non tutte le azioni richiedono una destinazione. Ad esempio, le azioni 
Help standard ignorano la destinazione e avviano semplicemente il 
sistema di aiuto. 

Barra strumenti Visualizza una riga visibile di icone pulsanti che, se si fa clic su di esse, 

provocano l'esecuzione di una certa azione da parte del programma, ad 
esempio la stampa del documento corrente. E possibile creare barre 
strumenti utilizzando il componente ActionBand toolbar TActionToolBar 
oppure utilizzando il componente multipiattaforma TToolBar. 



Se si sviluppano applicazioni multipiattaforma, fare riferimento al paragrafo 
delle liste di azioni" a pagina 8-25. 



Uso 



Che cosa e un' azione 



Poiche si sta sviluppando una propria applicazione, e possibile creare un insieme di 
azioni che e possibile utilizzare su diversi elementi deli'interfaccia utente. E possibile 
organizzarle per categorie che possono essere rilasciate su un menu come gruppo di 
azioni (ad esempio, Cut, Copy e Paste) oppure una alia volta (ad esempio, Tools I 
Customize). 

Un'azione corrisponde a uno o piu elementi deli'interfaccia utente, come comandi di 
menu o pulsanti della barra strumenti. Le azioni assolvono due funzioni: (1) 
rappresentano le proprieta comuni agli elementi deli'interfaccia utente, come lo stato 
attivo o inattivo di un controllo, e (2) rispondono alia stimolazione dei controlli, ad 
esempio, guando l'utente dell'applicazione fa clic su un pulsante o sceglie una voce 
di menu. E possibile creare un repertorio di azioni da rendere disponibili 
all'applicazione attraverso menu, pulsanti, barre strumenti, menu di scelta rapida, e 
cosi via. 

Le azioni sono associate ad altri componenti: 

• Client: Uno o piu client utilizzano l'azione. II client rappresenta molto spesso una 
voce di menu o un pulsante (ad esempio, TToolButton, TSpeedButton, TMenuItem, 
TButton, TCheckBox, TRadioButton, e cosi via). Le azioni possono risiedere anche in 
componenti ActionBand come TActionMainMenuBar e TActionToolBar. Quando il 
client riceve un comando dell'utente (come il clic del mouse), avvia un'azione 
associata. Di solito, l'evento OnClick di un client e associato all'evento OnExecute 
della sua azione. 
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• Destinazione: L'azione agisce in base alia destinazione. Di solito la destinazione e 
un controllo, come un campo memo o un controllo dati. Gli scrittori di componenti 
possono creare azioni specifiche per le necessita dei controlli che essi progettano e 
utilizzano e quindi assemblare quelle unit per creare applicazioni piu modulari. 
Non tutte le azioni utilizzano una destinazione. Ad esempio, le azioni Help 
standard ignorano la destinazione e avviano semplicemente il sistema di aiuto. 

Una destinazione puo anche essere un componente. Ad esempio, i controlli per 
dati cambiano la destinazione in un dataset associato. 

II client influisce sull'azione-l'azione risponde quando un client stimola l'azione. 
L'azione influisce anche sul client-le proprieta dell'azione aggiornano 
dinamicamente le proprieta del client. Ad esempio, se in fase di esecuzione un'azione 
e disabilitata (impostando la sua proprieta Enabled a false), ogni client di quell'azione 
e disabilitato e viene visualizzato come disabilitato. 

E possibile aggiungere, cancellare e riordinare le azioni utilizzando 1' Action Manager 
o l'Action List editor (che vengono visualizzati facendo doppio clic su un oggetto 
della lista di azioni, TActionList). Queste azioni saranno connesse successivamente a 
controlli client. 

Configurazione delle bande di azione 



Poiche le azioni non sono in grado di conservare alcuna informazione sul proprio 
layout (informazoni di aspetto o di posizionamento), C++Builder dispone di bande 
di azioni in grado di memorizzare questi dati. Le bande di azioni sono quindi un 
meccanismo che permette di specificare informazioni di disposizione e un insieme di 
controlli. E possibile rappresentare le azioni come elementi dell'interfaccia utente, 
come barre strumenti e menu. 

Gli insiemi di azioni vengono organizzati utilizzando l'Action Manager 
(TActionManager). E possibile utilizzare azioni standard gia predisposte o creare 
nuove azioni personali. 

Quindi si creano le bande di azioni: 

• Utilizzare TActionMainMenuBar per creare un menu principale. 

• Utilizzare TActionToolBar per creare una barra strumenti. 

Le bande di azioni agiscono come contenitori che contengono e rappresentano 
insiemi di azioni. In progettazione e possibile trascinare gli elementi dall' Action 
Manager editor sulla banda di azioni. In esecuzione, gli utenti dell'applicazione 
possono anche personalizzare i menu o le barre strumenti dell'applicazione 
utilizzando una finestra di dialogo simile all' Action Manager editor. 

Creazione di barre di strumenti e menu 



Questa sezione descrive il metodo consigliato per la creazione di menu e di barre 
strumenti in applicazioni Windows. Nello sviluppo multipiattaforma, e necessario 
utilizzare TToolBar e componenti menu, come TMainMenu, e organizzarli mediante le 
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liste di azioni (TActionList). Vedere "Configurazione delle liste di azioni" a 
pagina 8-25. 

Si utilizza 1' Action Manager per generare automaticamente barre strumenti e menu 
principali in base alle azioni incluse nell'applicazione. L' Action Manager gestisce le 
azioni standard e tutte le azioni custom che sono state scritte. Quindi si creano gli 
elementi del'interfaccia utente in base a queste azioni e si utilizzano le bande di 
azioni per rappresentare i vari elementi delle azioni elementi come voci di menu o 
come pulsanti di una barra strumenti. 

La procedura generale per la creazione di menu, barre strumenti e altre bande di 
azioni implica le seguenti fasi: 

• Collocare su una scheda un componente Action Manager. 

• Aggiungere azioni all'Action Manager, che le organizza per liste di azioni 
appropriate. 

• Creare le bande di azioni (cioe, il menu o la barra strumenti) per l'interfaccia 
utente. 

• Trascinare e rilasciare le azioni nell'interfaccia dell'applicazione. 
La seguente procedura spiega in maggior dettaglio le varie fasi. 

Per creare i menu e le barre strumenti utilizzando le bande di azioni: 

1 Dalla pagina Additional della Component palette, trascinare e rilasciare sulla 
scheda un componente Action Manager (TActionManager) nel punto in cui si 
desidera creare la barra strumenti o il menu. 

2 Se sul menu o sulla barra strumenti si vogliono delle immagini, trascinare e 
rilasciare sulla scheda un componente ImageList dalla pagina Win32 della 
Component palette. (E necessario aggiungere all'ImageList le immagini che si 
vogliono utilizzare oppure quelle fornito.) 

3 Dalla pagina Additional della Component palette, trascinare e rilasciare sulla 
scheda una o piu delle seguenti bande di azioni: 

• TActionMainMenuBar (per progettare menu principali) 

• TActionToolBar (per progettare barre strumenti) 

4 Connettere il componente ImageList al gestore di azioni: con il fuoco sull' Action 
Manager e nell'Object Inspector, selezionare il nome dell'ImageList dalla proprieta 
Images. 

5 Aggiungere le azioni al pannello delle azioni dell' Action Manager editor: 

• Fare doppio clic sull'Action Manager per visualizzare 1' Action Manager editor. 

• Fare clic sulla freccia verso il basso accanto al pulsante New Action (il pulsante 
piu a sinistra posto nell'angolo in alto a destra della pagina Actions, come 
mostrato nella Figure 8.2) e selezionare "New Action" oppure "New Standard 
Action". Viene mostrata una vista ad albero. Aggiungere al pannello delle 
azioni dell'Action Manager una o piu azioni o categorie di azioni. L' Action 
Manager aggiungera le azioni alia proprie liste di azioni. 
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Figura 8.2 Action Manager editor 
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to add actions to your application simply drag and drop from either 
Categories or Actions onto an existing ActionBar. 



6 Trascinare singole azioni o categorie di azioni dall' Action Manager editor e 
rilasciarle sul menu o sulla barra strumenti che si sta progettando. 

Per aggiungere azioni definite dall'utente, creare un nuovo T Action utilizzando il 
pulsante New Action e scrivendo un gestore di evento che definisca come rispondera 
al momento dell'attivazione. Per i dettagli, consultare "Cosa accade quando si 
scatena un'azione" a pagina 8-27. Una volta che si sono definite le azioni, e possibile 
trascinarle sui menu o sulle barre strumenti esattamente come le azioni standard. 



Aggiunta di colori, motivi o immagini a menu, pulsanti e barre di strumenti 

E possibile utilizzare le proprieta Background e BackgroundLayout per specificare un 
colore, un motivo o una bitmap da utilizzare in una voce di menu o in un pulsante. 
Queste proprieta permettono anche di configurare un banner da disporre sul lato 
sinistro o destro di un menu. 

Sfondo e layout vengono assegnati ai sottoelementi a partire dai rispettivi oggetti 
client di azioni. Se si desidera impostare lo sfondo degli elementi di un menu, fare 
clic nel Form designer sulla voce di menu che contiene gli elementi. Ad esempio, se si 
seleziona File e possibile modificare lo sfondo degli elementi visualizzati nel menu 
File. E possibile assegnare un colore, un motivo o una bitmap mediante la proprieta 
Background nell'Object Inspector. 

Utilizzare la proprieta BackgroundLayout per descrivere come collocare lo sfondo 
sull'elemento. I colori o le immagini possono essere collocati normalmente dietro 
l'intestazione, espansi in modo da adattarli all'area dell'elemento o affiancati in 
piccoli riquadri in modo da coprire l'area. 

Gli elementi con sfondi impostati a normale (blNormal), espanso (blStretch), o 
affiancato (blTile) vengono rappresentati con uno sfondo trasparente. Se si crea un 
banner, l'immagine completa viene collocata alia sinistra (blLeftBanner) o alia destra 
(blRightBanner) deU'elemento. E necessario accertarsi che le dimensioni siano 
corrette in quanta non viene espando o ristretto in modo da adattarlo all'area. 

Per modificare lo sfondo di una banda di azioni (cioe, di un menu principale o di una 
barra strumenti), selezionare la banda di azioni e scegliere il TActionClientBar 
utilizzando l'Action Band collection editor. E possibile impostare proprieta 
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Background e BackgroundLayout per specificare un colore, un motivo o una bitmap da 
utilizzare nell'intera barra strumenti o nel menu. 

Aggiunta di icone a menu e barre di strumenti 

E possibile aggiungere icone accanto alle voci di menu o sostituire le intestazioni 
delle barre strumenti con icone. Le bitmap o le icone vengono organizzate 
utilizzando un componete ImageList. 

1 Trascinare e rilasciare sulla scheda un componente ImageList prelevandolo dalla 
pagina Win32 della Component palette. 

2 Aggiungere all'elenco delle immagini quelle che si desidera utilizzare. Fare 
doppio clic sull'icona ImageList. Fare clic su Add, individuare e selezionare le 
immagini che si desidera utilizzare e, al termine, fare clic su OK. In Program Files \ 
Common Files \ Borland Shared \ Images sono incluse alcune immagini di esempio. 
(Le immagini dei pulsanti includono due versioni da utilizzare per i pulsanti attivi 
e non attivi.) 

3 Dalla pagina Additional della Component palette, trascinare e rilasciare sulla 
scheda una o piu delle seguenti bande di azioni: 

• TActionMainMenuBar (per progettare menu principali) 

• TActionToolBar (per progettare barre strumenti) 

4 Connettere la lista delle immagini al gestore di azioni. Per prima cosa, spostare il 
fuoco sull' Action Manager. In seguito, selezionare nell'Object Inspector il nome 
della lista di immagini dalla proprieta Images, come ad esempio ImageListl. 

5 Utilizzare Action Manager editor per aggiungere azioni all' Action Manager. E 
possibile associare un'immagine a un'azione impostandone la proprieta 
Imagelndex al suo numero nella lista di immagini. 

6 Trascinare le singole azioni o le categorie di azioni dall' Action Manager editor e 
rilasciarle sul menu o sulla barra strumenti. 

7 Per le barre strumenti in cui si vogliono visualizzare solo le icone, senza alcuna 
intestazione: selezionare la banda di azioni Toolbar e fare doppio clic sulla 
proprieta Items. Nell'editor della collezione, e possibile selezionare uno o piu 
elementi e impostare le rispettive proprieta Caption. 

8 Le immagini vengono visualizzate automaticamente sul menu o sulla barra 
strumenti. 

Creazione di barre di strumenti e menu personalizzabili dagli utenti 

Con l'Action Manager e possibile utilizzare bande di azioni per creare barre 
strumenti e menu personalizzabili. In esecuzione, gli utenti dell'applicazione 
potranno personalizzare le barre strumenti e i menu (bande di azioni) direttamente 
nell'interfaccia utente dell'applicazione utilizzando una finestra di dialogo di 
personalizzazione simile all' Action Manager editor. 

Per consentire all'utente dell'applicazione di personalizzare una banda di azioni 
nell'applicazione: 

1 Trascinare su una scheda un componente Action Manager. 
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2 Rilasciare i componenti banda di azioni (TActionMainMenuBar, TActionToolBar). 

3 Fare doppio clic sull'Action Manager per visualizzare l'Action Manager editor: 

• Aggiungere le azioni che si desidera utilizzare nell'applicazione. Aggiunge 
anche l'azione Customize, visualizzata alia fine dell'elenco delle azioni 
standard. 

• Trascinare un componente TCustomizeDlg dalla pagina Additional e rilasciarlo 
sulla scheda e connetterlo all' 'Action Manager utilizzando la proprieta 
ActionManager. Si deve specificare un nome file in cui registrare le 
personalizzazioni fatte dall'utente. 

• Trascinare le azioni sui componenti banda di azioni. (Assicurarsi di aggiungere 
l'azione Customize alia barra strumenti o al menu.) 

4 Completare l'applicazione. 

Quando si compila e si esegue l'applicazione, gli utenti potranno accedere a un 
comando Customize che visualizza una finestra di dialogo di personalizzazione 
simile all' Action Manager editor. Potranno trascinare voci di menu e creare barre 
strumenti utilizzando le stesse azioni fornite nell' Action Manager. 

Occultamento di elementi e categorie inutilizzate nelle bande di azioni 

Uno dei vantaggi derivanti dall'utilizzo delle ActionBands consiste nel fatto che gli 
elementi e le categorie inutilizzati possono essere nascosti all'utente. Col passare del 
tempo, le bande di azioni diventano personalizzate per gli utenti dell'applicazione, 
visualizzando solo gli elementi che essi utilizzano e nascondendo il resto. Gli 
elementi nascosti possono diventare nuovamente visibili mediante la pressione di un 
pulsante a discesa. Inoltre, l'utente puo ripristinare la visibility di tutti gli elementi 
della banda di azioni reimpostando le statistiche di utilizzo dalla finestra di dialogo 
di personalizzazione. L'occultamento degli elementi e il comportamento predefinito 
delle bande di azioni, ma puo essere modificato in modo da evitare di nascondere 
singoli elementi, tutti gli elementi di una particolare raccolta (ad esempio, il menu 
File) o di tutti gli elementi in una certa banda di azioni. 

II gestore di azioni tiene traccia del numero di volte che un'azione e stata richiamata 
dall'utente, memorizzando tale numero nel campo UsageCount del TActionClientltem 
associate II gestore di azioni registra anche il numero di volte che l'applicazione e 
stata stata eseguita, che si potrebbe definire come il numero di sessioni, e il numero 
di sessione in cui una azione e stata utilizzata per l'ultima volta. II valore di 
UsageCount viene utilizzato per individuare il numero massimo di sessioni di 
mancato utilizzo dell'elemento, prima che l'elemento stesso venga nascosto, il quale 
viene quindi confrontato con la differenza fra il numero di sessione corrente e il 
numero di sessione dell'ultimo utilizzo dell'elemento. Se la differenza e maggiore del 
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numero impostato in Priority Schedule, l'elemento viene nascosto. I valori predefiniti 
di PrioritySchedule vengono visualizzati nella tabella seguente: 

Tabella 8.2 Valori predefiniti della proprieta PrioritySchedule del gestore di azioni 
Numero di sessioni in cui e 

stato utilizzato un elemento Numero di sessioni per cui un elemento rimarra visibile 
di una banda di azioni dopo il suo ultimo utilizzo 



0,1 


3 


2 


6 


3 


9 


4,5 


12 


6-8 


17 


9-13 


23 


14-24 


29 


25 o piu 


31 



E possibile disattivare l'occultamento degli elementi in progettazione. Per impedire 
che una certa azione (e tutte le raccolte che la contengono) venga nascosta, 
individuare il suo oggetto TActionClientltem e impostarne la proprieta UsageCount a - 
1. Per impedire l'occultamento di un'intera raccolta di elementi, come il menu File o 
anche la barra del menu principale, individuare l'oggetto TActionClients associato 
alia raccolta e impostarne la proprieta Hidellnused a false. 

Uso delle liste di azioni 



I contenuti di questa sezione si riferiscono alia configurazione delle barre strumenti e 
dei menu per lo sviluppo multipiattaforma. Per sviluppo in Windows e possibile 
utilizzare anche i metodi descritti di seguito. Tuttavia, 1' utilizzo delle bande di azioni 
e piu semplice e offre piu possibility. Le liste di azioni saranno gestite 
automaticamente dall' Action Manager. Per informazioni sull'utilizzo di bande di 
azioni e dell'Action Manager, consultare la sezione "Organizzazione delle azioni per 
barre e menu" a pagina 8-17. 

Le liste di azioni gestiscono una lista di azioni che l'applicazione puo eseguire in 
risposta a qualcosa fatto dall'utente. Utilizzando oggetti action, e possibile 
centralizzare le funzioni eseguite dall'applicazione a partire dall'interfaccia utente. In 
questo modo, non solo e possibile condividere il codice comune per eseguire 
determinate azioni (ad esempio, quando un pulsante di una barra strumenti e voce di 
menu compiono la stessa operazione), ma si dispone anche di un singolo modo 
centralizzato per attivare e disattivare le azioni a seconda dello stato 
dell'applicazione. 

Configurazione delle liste di azioni 



La configurazione delle liste di azioni e abbastanza facile una volta comprese le 
operazioni di base coinvolte: 
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• Creazione delle lista di azioni. 

• Aggiunta di azioni alia lista di azioni. 

• Impostazione delle proprieta delle azioni. 

• Collegamento del client all'azione. 

Le operazioni di base sono spiegate in dettaglio qui di seguito: 

1 Rilasciare un oggetto TActionList sulla scheda o sul modulo dati. (ActionList e 
sulla pagina Standard della Component palette.) 

2 Fare doppio clic sull'oggetto TActionList per visualizzare 1' Action List editor. 

1 Utilizzare una delle azioni predefinite elencate nell'editor: fare clic destro e 
scegliere New Standard Action. 

2 Le azioni predefinite sono organizzate per categorie (come Dataset, Edit, Help e 
Window) nella finestra di dialogo Standard Action Classes. Selezionare tutte le 
azioni standard che si vogliono aggiungere alia lista di azioni e fare clic su OK. 

oppure 

3 Creare una nuova azione personale: fare clic destro e scegliere New Action. 

3 Impostare nell'Object Inspector le proprieta di ogni azione. (le proprieta che si 
impostano influiscono su ogni client dell'azione) 

La proprieta Name identifica l'azione e le altre proprieta ed eventi (Caption, 
Checked, Enabled, HelpContext, Hint, Imagelndex, ShortCut, Visible e Execute) 
corrispondono alle proprieta e agli eventi dei suoi controlli client. Le proprieta 
corrispondenti del client hanno di solito, ma non necessariamente, lo stesso nome 
della proprieta client corrispondente. Ad esempio, la proprieta Enabled di 
un'azione corrisponde alia proprieta Enabled di un TToolButton. Tuttavia, la 
proprieta Checked di un'azione corrisponde alia proprieta Down di un TToolButton. 

4 Se si utilizzano le azioni predefinite, l'azione include una risposta standard che si 
verifica automaticamente. Se si sta creando un'azione personale, e necessario 
scrivere un gestore di evento che definisca come risponde l'azione quando viene 
scatenata. Per i dettagli, consultare "Cosa accade quando si scatena un'azione" a 
pagina 8-27. 

5 Collegare le azioni nella lista di azioni ai client che ne hanno bisogno: 

• Fare clic sul controllo (come un pulsante o un voce di menu) sulla scheda o sul 
modulo dati. NellObject Inspector, la proprieta Action elenca le azioni 
disponibili. 

• Selezionare quella che si desidera. 

Le azioni standard, come TEditDelete o TDataSetPost, eseguono tutte l'azione che ci si 
aspetta. Se occorre, e possibile consultare la Guida di riferimento in linea per i 
dettagli sulle modalita di funzionamento di tutte le azioni standard. Se si dovranno 
scrivere azioni personalizzate, sara necessario approfondire cio che avviene quando 
l'azione viene scatenata. 
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Cosa accade quando si scatena un'azione 



Quando si scatena un evento, si verifica una serie di eventi destinati principalmente 
alle azioni generiche. Poi, se l'evento non gestisce l'azione, si verifica un'alira 
sequenza di eventi. 

Risposta con eventi 

Quando si fa clic su un componente client o su un controllo client, o si agisce 
altrimenti su di esso, si verifica una serie di eventi a cui e possibile rispondere. Ad 
esempio, il seguente codice illustra il gestore di evento di un'azione che commuta la 
visibilita di una barra strumenti quando l'azione viene eseguita: 

void __fastcall TForml: : ActionlExecute (TObject *Sender) 

{ 

// Toggle Toolbar!.' s visibility 
ToolBarl->Visible = !ToolBarl->Visible; 

} 

E possibile fornire un gestore di evento che risponda a uno dei tre diversi livelli: 
l'azione, la lista di azioni o l'applicazione. Ci si deve occupare di cio solo se si utilizza 
una nuova azione generica invece di un'azione standard predefinita. Se si utilizzano 
le azioni standard non ce ne si deve occupare, perche le azioni standard hanno un 
comportamento incorporato che viene eseguito quando si verificano questi eventi. 

I gestori di evento risponderanno agli eventi in base al seguente ordine: 

• Lista di azioni 

• Applicazione 

• Azione 

Quando l'utente fa clic su un controllo client, C++Builder chiama il metodo Execute 
dell'azione che dapprima rimanda alia lista di azioni, quindi all'oggetto Application, 
quindi all'azione stessa nel caso non venga gestita ne dalla lista di azioni ne 
dall'oggetto Application. Per essere piu precisi, C++Builder segue questa sequenza 
di smistamento quando cerca un modo per rispondere all'azione di un utente: 

1 Se si fornisce un gestore di evento OnExecute per la lista di azioni e tale gestore e in 
grado di gestire l'azione, l'applicazione procede. 

II gestore di evento della lista di azioni ha un parametro di nome Handled, che, per 
impostazione predefinita, restituisce false. Se il gestore e stato assegnato ed e in 
grado di gestire l'evento restituisce true, e la sequenza di elaborazione termina a 
questo punto. Per esempio: 

void __fastcall TForml: :ActionListlExecuteAction (TBasicAction *Action, bool &Handled) 
{ 

Handled = true; 

} 

Se non si imposta Handled a true nel gestore di evento della lista di azioni, allora 
l'elaborazione continua. 

2 Se non e stato preparato un gestore di evento OnExecute per la lista di azioni 
oppure se il gestore di evento non e in grado di gestire l'azione, viene scatenato il 
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gestore di evento OnActionExecute dell'applicazione. Se gestisce l'azione, 
l'applicazione precede. 

L'oggetto globale Application riceve un evento OnActionExecute nel caso nessuna 
delle liste di azioni dell'applicazione sia in grado di gestire un evento. Come il 
gestore di evento OnExecute dell'elenco di azioni, il gestore di OnActionExecute ha 
un parametro Handled che, per impostazione predefinita, restituisce false. Se un 
gestore di evento e stato assegnato ed e in grado di gestire l'evento, restituisce true 
e la sequenza di elaborazioni termina a questo punto. Per esempio: 

void fastcall TForml: :ApplicationExecuteAction(TBasicAction *Action, bool SHandled) 

{ 

// Prevent execution of all actions in Application 
Handled = true; 

} 

3 Se il gestore di evento OnExecute dell'applicazione non gestisce l'azione, viene 
scatenato il gestore di evento OnExecute dell'azione. 

E possibile utilizzare le azioni incorporate o creare proprie classi di azione che 
sappiano come operare su classi di destinazione specifiche (ad esempio i controlli di 
editing). Se non viene trovato, a nessun livello, un gestore di evento, successivamente 
l'applicazione prova a trovare una destinazione su cui eseguire l'azione. Se 
l'applicazione individua una destinazione che sa come trattarla, richiama l'azione. 
Per i dettagli su come l'applicazione individua una destinazione in grado di 
rispondere a una classe di azione predefinita, consultare il paragrafo successive 

Come le azioni trovano le proprie destinazioni 

"Cosa accade quando si scatena un' azione" a pagina 8-27 descrive il ciclo di 
esecuzione che si verifica quando un utente richiama un'azione. Se a nessun gestore 
di evento e stato assegnato il compito di rispondere all'azione, a livello di lista di 
azioni, di applicazione o di azione, allora l'applicazione prova a identificare un 
oggetto di destinazione a cui puo essere affidato l'incarico. 

L'applicazione cerca la destinazione utilizzando la seguente sequenza: 

1 Controllo attivo: L'applicazione cerca come possibile destinazione dapprima se e'e 
un controllo attivo. 

2 Scheda attiva: Se l'applicazione non trova un controllo attivo o se il controllo 
attivo non puo agire come destinazione, analizza la ActiveForm a video. 

3 Controlli sulla scheda: Se la scheda attiva non e una destinazione appropriata, 
l'applicazione analizza gli altri controlli sulla scheda attiva per trovare una 
destinazione. 

Se non viene individuata nessuna destinazione, nel momento in cui si scatena 
l'evento non accade niente. 

Alcuni controlli possono estendere la ricerca per cercare di rimettere la destinazione 
a un componente associato; ad esempio, i controlli data-aware si rivolgono al 
componente dataset associato. Inoltre, alcune azioni predefinite, ad esempio, quelle 
della finestra di dialogo File Open, non utilizzano una destinazione. 
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Aggiornamento delle azioni 



Quando 1' applicazione e inattiva, l'evento Onllpdate si verifica per ogni azione 
collegata con un controllo o con una voce di menu visualizzati in quel momento. Cio 
fornisce un'opportunita alle applicazioni di eseguire il codice centralizzato per 
attivare e disattivare, selezionare e deselezionare, e cosi via. Per esempio, il seguente 
codice illustra il gestore di evento Onllpdate per un'azione che viene "selezionata" 
quando la barra strumenti e visibile: 

void __fastcall TForml: :ActionlUpdate (TObject *Sender) 

{ 

// Indicate whether ToolBarl is currently visible 
((TAction *) Sender) ->Checked = ToolBarl->Visible; 

} 

Non aggiungere al gestore di evento Onllpdate codice con lunghi tempi di 
esecuzione. Questa operazione viene eseguita ogniqualvolta l'applicazione e inattiva. 
Se il gestore di evento impiega troppo tempo, influenzera negativamente le 
prestazioni dell'intera applicazione. 



Classi di azione predefinite 



E possibile aggiungere all'applicazione azioni predefinite facendo clic destro 
sull' Action Manager e selezionando il comando New Standard Action. Verra 
visualizzata la finestra di dialogo New Standard Action Classes che elenca le classi di 
azione predefinite e le azioni standard associate. Queste sono azioni gia incluse in 
C++Builder e sono oggetti che eseguono automaticamente determinate azioni. Le 
azioni predefinite sono organizzate nelle seguenti classi: 



Tabella 8.3 Classi di azioni 



Format 



Help 



Window 



Descrizione 



Azioni standard di editing: Utilizzate con controlli di editing come 
destinazione. TEditAction e la classe di base dei discendenti, ognuno dei 
quali ridefinisce individualmente il metodo ExecuteTarget in modo da 
implementare le attivita di copia, taglia e incolla utilizzando la clipboard. 

Azioni standard di formattazione: Utilizzate con controlli rich text per 
impostare opzioni di formattazione del testo come grassetto, corsivo, 
sottolineato, barrato, e cosi via.TRichEditAction e la classe di base dei 
discendenti, ognuno dei quali ridefinisce individualmente i metodi 
ExecuteTarget e UpdateTarget in modo da implementare le attivita di 
formattazione deila destinazione. 

Azioni standard di Help: Utilizzate con qualsiasi destinazione. 
THelpAction e la classe di base dei discendenti, ognuno dei quali 
ridefinisce individualmente il metodo ExecuteTarget in modo da passare 
il comando a un sistema di Help. 

Azioni standard di finestra: Utilizzate con schede come destinazioni in 
un'applicazione MDI. TWindoivAction e la classe di base dei discendenti, 
ognuno dei quali ridefinisce individualmente il metodo ExecuteTarget in 
modo da implementare le attivita di disposizione, sovrapposizione, 
chiusura o affiancamento di finestre figlio in applicazioni MDI. 
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Tabella 8.3 Classi di azioni 



Classe 


Descrizione 


File 


Azioni su file: Utilizzate per operazioni su file come File Open, File Run 
o File Exit. 


Search 


Azioni di ricerca: Utilizzato con opzioni di ricerca. TSearchAction 
implementa il comportamento comune per quelle azioni che 
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immettere una stringa di ricerca per effettuare ricerche in un controllo di 
editing. 


Tab 


Azioni per controlli multipagina: Utilizzate per spostarsi fra le varie 
pagine di un controllo multipagina, come per i pulsanti Prev e Next di 
un wizard. 


List 
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dialogo. TDialogAction implementa il comportamento comune per quelle 
azioni che, quando eseguite, visualizzano una finestra di dialogo. Ogni 
classe discendente rappresenta una finestra di dialogo specifica. 


Internet 


Azioni Internet: Utilizzato per funzioni quali la navigazione in Internet, 
lo scaricamento di file e 1'invio di posta. 


DataSet 


Azioni DataSet: Utilizzato con componenti dataset come destinazione. 
TDataSetAction e la classe di base dei discendenti, ognuno dei quali 
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modo da implementare le attivita di navigazione ed editing della 
destinazione. 

TDataSetAction introduce una proprieta DataSource che garantisce che le 
azioni vengano eseguite su quel dataset. Se DataSource e NULL, viene 
usato il controllo associato ai dati che in quel momento ha il fuoco. 


Tools 


Strumenti: Strumenti aggiuntivi come TCustomizeActionBars per la 
visualizzazione automatica della finestra di dialogo di personalizzazione 
delle bande di azioni. 



Tutti gli oggetti azione sono descritti nella Guida di riferimento in linea. Per i dettagli 
sul loro funzionamento, consultare la Guida in linea. 



Scrittura di componenti azione 

E possibile anche creare proprie classi di azione predefinite. Quando si scrivono 
proprie classi di azione, e possibile incorporare la capacita di essere eseguite su 
alcune classi di oggetti di destinazione. A questo punto, e sara possibile utilizzare le 
azioni custom in modo analogo a quello utilizzato per le classi di azione predefinite. 
Vale a dire, se l'azione e in grado di individuare e di applicare se stessa a una classe 
di destinazione, e possibile assegnare semplicemente l'azione a un controllo client, ed 
essa agira sulla destinazione che sia necessario scrivere un gestore di evento. 

Gli scrittori di componenti possono utilizzare le classi nelle unit QStdActns e 
DBActns come esempi per derivare le proprie classi di azione per implementare 
comportamenti specifici per alcuni controlli o componenti. Le classi di base di queste 
azioni specializzate (TEdit Action, TWindow Action, e cosi via) di solito ridefiniscono 
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Handles! "arget, UpdateTarget e altri metodi in modo da limitare la destinazione 
dell'azione a una determinata classe di oggetti. Normalmente, le classi discendenti 
ridefiniscono ExecuteTarget per eseguire un compito specialistico. Questi metodi sono 
descritti nella tabella seguente : 



Metodo Descrizione 

Handles! ar get Chiamato automaticamente quando 1'utente richiama un oggetto (come un 

pulsante di una barra pulsanti o una voce di menu) collegato con l'azione. II 
metodo Handles! ar get permette all'oggetto action di indicare se e opportuna 
o meno l'esecuzione, utilizzando come "destinazione" l'oggetto specificato 
dal parametro !arget. Per i dettagli, consultare "Come le azioni trovano le 
proprie destinazioni" a pagina 8-28. 

Update!arget Chiamato automaticamente quando 1'applicazione e inattiva in modo che le 

azioni si possano aggiornare in funzione delle condizioni. Utilizzare al posto 
di OnUpdateAction. Per i dettagli, consultare "Aggiornamento delle azioni" a 
pagina 8-29. 

Execute! arget Chiamato automaticamente al posto di OnExecute quando l'azione viene 

scatenata in risposta all'azione di un utente (ad esempio, quando 1'utente 
seleziona una voce di menu o preme un pulsante strumento collegato con 
questa azione). Per i dettagli, consultare "Cosa accade quando si scatena 
un'azione" a pagina 8-27. 



Registrazione delle azioni 



Quando si scrivono le proprie azioni, e possibile registrarle in modo da consentirne la 
visualizzazione nell' Action List editor. Le azioni vengono registrate e de-registrate 
utilizzando le routine globali nella unit Actnlist: 

extern PACKAGE void fastcall RegisterActions (const AnsiString CategoryName, TMetaClass* 

const * AClasses, const int AClasses_Size, TMetaClass* Resource); 

extern PACKAGE void fastcall UnRegisterActions (TMetaClass* const * AClasses, const int 

AClasses_Size) ; 

Quando si chiama RegisterActions, le azioni che si registrano vengono visualizzate 
nell' Action List editor in modo che siano utilizzabili da parte delle applicazioni. E 
possibile indicare un nome di categoria per organizzare le azioni, oltre a un 
parametro Resource che permette di indicare i valori predefiniti delle proprieta. 

Per esempio, il seguente codice registra con 1'IDE le azioni standard nella unit 

My Action: 

namespace MyAction 
{ 

void __fastcall PACKAGE Register!) 
{ 

// code goes here to register any components and editors 
TMetaClass classes [2] = {__classid (TMyActionl) , __classid (TMyAction2 ) } ; 
RegisterActions ("MySpecialActions", classes, 1, NULL) ; 

} 

} 
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Quando si chiama UnRegister Actions, le azioni non vengono piu visualizzate 
nell' Action List editor. 



Creazione e gestione dei menu 



I menu forniscono agli utenti un modo facile per eseguire comandi raggruppati 
logicamente. II Menu Designer di Delphi consente di aggiungere facilmente un 
menu, gia progettato o confezionato su misura, alia scheda. E sufficiente aggiungere 
un componente menu alia scheda, aprire il Menu Designer e scrivere le voci menu 
direttamente nella finestra del Menu Designer. E possibile aggiungere o cancellare le 
voci di menu, o trascinarle e rilasciarle per risistemarle in fase di progettazione. 

Non occorre neanche eseguire il programma per vedere i risultati-la progettazione e 
immediatamente visibile nella scheda, che appare proprio come apparira in fase di 
esecuzione. II codice pud modificare i menu anche in fase di esecuzione, per fornire 
ulteriori informazioni o opzioni aU'utente. 

Questo capitolo spiega come usare il Menu Designer per progettare barre di menu e 
menu (locali) a comparsa. Esso tratta i seguenti modi di lavorare con i menu in fase di 
progettazione e in fase di esecuzione: 

• Apertura del Menu Designer. 

• Costruzione di menu. 

• Editing delle voci di menu nell'Object Inspector. 

• Uso del menu contestuale Menu Designer. 

• Uso dei modelli di menu. 

• Salvataggio di un menu come modello. 

• Aggiunta di immagini alle voci di menu. 

Figura 8.3 Terminologia dei menu 

m-M-Hum view Proisct Run com p Voci di menu sulla barra dei menu 

Find... 
Replace... 
Search Again 

Separatore 



Acceleratore di 
tastiera 



incremental Search 



Ctrl+L 

Shitt+Ctrl+S- 



Go to Line Number 



Browse Symbol 



- Voci di menu in un elenco di menu 



- Scorciatoia di tastiera 



Apertura del Menu Designer 



I menu vengono progettati utilizzando il Menu Designer. Prima di iniziare a usare il 
Menu Designer, e necessario aggiungere alia scheda un componente TMainMenu o 
TPopupMenu. Entrambi i componenti menu sono collocati sulla pagina Standard 
della Component palette. 

Figura 8.4 Componenti MainMenu e PopupMenu 

standard Ja^m* — Componente MainMenu 
I^T | %| — Componente PopupMenu 
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Un componente MainMenu crea un menu che viene collegato alia barra del titolo 
della scheda. Un componente PopupMenu crea un menu che appare quando l'utente 
fa clic con il tasto destro nella scheda. I menu a comparsa non hanno una barra di 
menu. 

Per aprire il Menu Designer, selezionare un componente menu sulla scheda, e quindi 
scegliere: 

• Fare doppio clic sul componente menu, 
oppure 

• Dalla pagina Properties dell'Object Inspector, selezionare la proprieta Items, e 
quindi fare doppio clic [Menu] nella colonna Value, oppure fare clic sul pulsante 
ellissi (...). 

II Menu Designer viene visualizzato, con la prima voce di menu (vuota) 
evidenziata nel Designer, e la proprieta Caption selezionata nell'Object Inspector. 

Figura 8.5 Menu Designer per un menu principale 



Segnaposto per la 
voce di menu 




Costruzione di menu 



Si aggiunga un componente menu alia scheda, o alle schede, per ogni menu da 
includere nell'applicazione. E possibile costruire ciascuna struttura di menu 
completamente ex-novo, o iniziare da uno dei modelli di menu predefiniti. 

Questa sezione illustra i principi per la creazioni di un menu in fase di progettazione. 
Per ulteriori informazioni sui modelli di menu, consultare "Uso dei modelli di menu" 
a pagina 8-41. 

Assegnazione dei nomi dei menu 

Come tutti i componenti, quando alia scheda viene aggiunto un componente menu, 
C++Builder gli da un nome predefinito; per esempio, MainMenul. E possibile dare al 
menu un nome piu significative 

C++Builder aggiunge il nome del menu alia dichiarazione di tipo della scheda, e 
quindi questo nome appare nel Component list. 
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Assegnazione dei nomi delle voci di menu 

Al contrario del componente menu stesso, occorre dare esplicitamente un nome alle 
voci di menu via via che vengono aggiunte alia scheda. E possibile farlo in due modi: 

• Scrivere direttamente il valore per la proprieta Name. 

• Scrivere prima il valore per la proprieta Caption, e lasciare a C++Builder il compito 
di derivare la proprieta Name dal caption. 

Per esempio, se viene data a una voce di menu una valore della proprieta Caption 
di File, C++Builder assegna alia voce di menu una proprieta Name di Filel. Se viene 
compilata la proprieta Name prima di compilare la proprieta Caption, C++Builder 
lascia la proprieta Caption vuota finche non viene scritto un valore. 

Se vengono immessi nella proprieta Caption caratteri non validi per gli 
identificatori C++, C++Builder modifica conseguentemente la proprieta Name. Per 
esempio, se si desidera che il caption inizi con un numero, C++Builder fa 
precedere il numero con un carattere per derivare la proprieta Name. 

La seguente tabella mostra alcuni esempi di cio, presupponendo che tutte le voci 
di menu mostrate appaiano nella stessa barra di menu. 

Tabella 8.4 Esempi di caption e loro nomi derivati 



Caption del 


Nome deriva 




&File 


Filel 


Rimuove la e commerciale 


&File (2nd occurrence) 


File2 


Ordina numericamente le voci duplicate 


1234 


N12341 


Aggiunge una lettera prima e l'ordine numerico 


1234 (2nd occurrence) 


N12342 


Aggiungi un numero per eliminare l'ambiguita al 
nome derivato 


$@@@# 


Nl 


Rimuove tutti i caratteri non standard, aggiungendo 
una lettere prima e l'ordine numerico 


- (hyphen) 


N2 


Ordinamento numerico della seconda occorrenza di 
caption senza alcun carattere standard 



Come il componente menu, C++Builder aggiunge qualsiasi nome di voce di menu 
alia dichiarazione di tipo della scheda, e quei nomi quindi appaiono nella 
Component list. 



Aggiunta, inserimento e cancellazione delle voci di menu 

Le seguenti procedure descrivono come eseguire i principali compiti coinvolti nella 
costruzione della struttura del menu. Ciascuna procedura assume che sia aperta la 
finestra Menu Designer. 

Per aggiungere voci di menu in fase di progettazione: 

1 Selezionare la posizione in cui creare la voce di menu. 

Se il Menu Designer e stato appena aperto, la prima posizione sulla barra di menu 
e gia selezionata. 
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2 Iniziare a scrivere per immettere il caption. O immettere prima la proprieta Name 
collocando specificamente il cursore nell'Object Inspector e immettendo un valore. 
In questo caso, occorre allora selezionare di nuovo la proprieta Caption ed 
immettere un valore. 

3 Premere Invio. 

Viene selezionato il successivo placeholder per una voce di menu. 

Se prima viene immessa la proprieta Caption, usare i tasti cursore per ritornare alia 
voce di menu appena immessa. C++Builder visualizzera di aver compilato la 
proprieta Name in base al valore immesso per il caption. (Consultare il paragrafo 
"Assegnazione dei nomi delle voci di menu" a pagina 8-34.) 

4 Continuare l'immissione dei valori per le proprieta Name e Caption per ciascuna 
nuova voce da creare, o premere Esc per ritornare alia barra dei menu. 

Usare i tasti cursore per spostarsi dalla barra dei menu nel menu, e quindi 
spostarsi tra le voci dell'elenco; premere Invio per completare un'azione. Per 
ritornare alia barra dei menu, premere Esc. 

Per inserire una nuova voce di menu vuota: 

1 Collocare il cursore su una voce di menu. 

2 Premere Ins. 

Le voci di menu vengono inserite a sinistra della voce selezionata sulla barra dei 
menu, e sopra la voce selezionata nell'elenco del menu. 

Per cancellare una voce di menu o comando: 

1 Collocare il cursore sulla voce di menu da cancellare. 

2 Premere Del. 

Non e possibile cancellare il placeholder predefinito che appare sotto l'ultima voce 
immessa nell'elenco del menu, o vicino all'ultima voce sulla barra dei menu. Questo 
placeholder non appare nel menu in fase di esecuzione. 
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Figura 8.6 Aggiunta di voci di menu a un menu principale 
Le funzionalita WYSIWYG del Menu Designer mostrano le 
voci di menu man mano che il menu viene create 
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Viene creato un oggetto TMenultem e la 
proprieta Name viene impostata alia propriety 
Caption specificata (eliminando eventuali 
caratteri non ammessi e aggiungendo un 
suffisso numerico). 



Aggiunta di barre separatrici 

Le barre separatrici inseriscono una riga tra le voci di menu. E possibile usare queste 
barre per indicare raggruppamenti all'interno dell'elenco del menu, o semplicemente 
per fornire un'interruzione visuale di un elenco. 

Per rendere la voce di menu una barra separatrice, scrivere un trattino (-) per il 
caption. 

Specifica dei tasti di scelta rapida e delle scorciatoie di tastiera 

I tasti di scelta rapida consentono all'utente di accedere ad comando di menu dalla 
tastiera premendo Alt+ la lettera appropriata, indicata nel codice dalla e commerciale 
precedente. Nel menu, la lettera dopo la e commerciale appare sottolineata. 

C++Builder controlla automaticamente l'esistenza di tasti di scelta rapida duplicati e 
li corregge in fase di esecuzione. Questo comportamento garantisce che tutti i menu 
generati dinamicamente in fase di esecuzione non contengano tasti di scelta rapida 
duplicati e che tutti gli elementi di menu abbiano un tasto di scelta rapida. E possibile 
disattivare questo controllo automatico impostando la proprieta AutoHotkeys di un 
elemento di menu a maManucd. 

Per specificare un tasti di scelta rapida: 

• Aggiungere una e commerciale davanti alia lettera appropriata. 

Per esempio, per aggiungere un comando di menu Save con la S come tasto 
acceleratore, scrivere &Save. 

Le scorciatoie di tastiera consentono all'utente di eseguire l'azione senza accedere 
direttamente al menu, scrivendo la combinazione di tasti della scorciatoia. 

Per specificare una scorciatoia di tastiera: 
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• Usare l'Object Inspector per immettere un valore per la proprieta ShortCut, o 
selezionare una combinazione di tasti dall'elenco a discesa. 

Questo elenco e solo un sottoinsieme delle combinazioni valide che possono essere 
scritte. 

Quando viene aggiunta una scorciatoia, essa appare vicino al titolo della voce di 
menu. 

Le scorciatoie di tastiera, a differenza degli acceleratori, non sono soggette al 
controllo automatico per l'esistenza di duplicati. II controllo di univocita deve essere 
eseguito manualmente. 

Creazione di sottomenu 



Molti menu di applicazioni contengono elenchi a discesa che appaiono vicino a una 
voce di menu per fornire ulteriori comandi collegati. Tali elenchi vengono indicati da 
una freccia a destra della voce di menu. C++Builder supporta tutti i livelli di 
sottomenu desiderati. 

Organizzando la struttura dei menu in questo modo, si puo salvare lo spazio 
verticale dello schermo. Tuttavia, per progettazioni ottimali forse e meglio non usare 
piu di due o tre livelli nella progettazione dell'interfaccia. (Per i menu popup, 
potrebbe essere opportuno usare un solo sottomenu.) 

Figura 8.7 Strutture di menu annidate 
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Per creare un sottomenu: 

1 Selezionare la voce di menu sotto cui si desidera creare un sottomenu. 

2 Premere Ctrl — > per creare il primo segnaposto, o fare clic con il tasto destro e 
scegliere Create Submenu. 

3 Scrivere un nome per la voce del sottomenu, o trascinare una voce di menu 
esistente su questo segnaposto. 

4 Premere Invio, o I, per creare il successivo segnaposto. 

5 Ripetere i punti 3 e 4 per ciascuna voce da creare nel sottomenu. 

6 Premere Esc per ritornare al precedente livello di menu. 
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Creazione di sottomenu per retrocessione dei menu esistenti 

E possibile creare un sottomenu inserendo una voce dalla barra dei menu (o da un 
modello di menu) tra le voci di menu di un elenco. Quando un menu viene spostato 
in una struttura di menu esistente, tutte le voci associate lo seguono, creando un 
menu completamente intatto. Questo vale anche per i sottomenu. Spostando una 
voce di menu in un sottomenu esistente si crea solo un altro livello di annidamento. 

Spostamento delle voci di menu 

In fase di progettazione, per spostare le voci di menu basta semplicemente trascinare 
e rilasciare. E possibile spostare le voci della barra dei menu, o in un altro posto 
dell'elenco del menu, o in un menu completamente diverso. 

L'unica eccezione a cio e di tipo gerarchico: non e possibile degradare una voce dalla 
barra dei menu nel suo stesso menu; ne e possibile spostare una voce di menu nel suo 
stesso sottomenu. Pero, si puo spostare qualsiasi voce in un altro menu, 
indipendentemente dalla sua posizione originaria. 

Durante il trascinamento, il cursore cambia forma per indicare se e possibile 
rilasciare la voce di menu nella nuova locazione. Quando viene spostata una voce di 
menu, si sposta anche qualsiasi voce al di sotto di essa. 

Per spostare una voce di menu lungo la barra dei men:, 

1 Trascinare la voce lungo la barra dei menu finche la punta della freccia del cursore 
di trascinamento punta alia nuova locazione. 

2 Rilasciare il pulsante del mouse per abbandonare la voce di menu nella nuova 
locazione. 

Per spostare una voce in un elenco di menu: 

1 Trascinare la voce lungo la barra dei menu finche la punta della freccia del cursore 
di trascinamento punta al nuovo menu. 

Questo obbliga il menu ad aprirsi, consentendo di trascinare la voce nella sua 
nuova locazione. 

2 Trascinare la voce di menu nell'elenco, rilasciando il pulsante del mouse per 
abbandonare la voce di menu nella nuova locazione. 

Aggiunta di immagini alle voci di menu 

Le immagini possono aiutare gli utenti a navigare nei menu facendo corrispondere 
glyph e immagini all'azione della voce di menu, in modo analogo alle immagini della 
barra strumenti. E possibile aggiungere singole bitmap alle voci di menu oppure e 
possibile organizzare le immagini per l'applicazione in una lista di immagini e 
aggiungerle a un menu prelevandole dalla lista di immagini. Se nell'applicazione si 
utilizzano numerose bitmap delle stesse dimensioni, e utile collocarle in una lista di 
immagini. 

Per aggiungere una singola immagine a un menu o a una voce di menu, impostarne 
la proprieta Bitmap in modo che faccia riferimento al nome della bitmap che sara 
utilizzata sul menu o sulla voce di menu. 
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Per aggiungere un'immagine a una voce di menu utilizzando una lista di immagini: 

1 Rilasciare un oggetto TMainMenu o TPopupMenu su una scheda. 

2 Rilasciare un oggetto TImageList sulla scheda. 

3 Aprire TImageList editor facendo doppio clic sull'oggetto TImageList. 

4 Fare clic su Add per selezionare la bitmap o il gruppo di bitmap da usare nel 
menu. Fare clic su OK. 

5 Impostare la proprieta Images dell'oggetto TMainMenu o TPopupMenu all'ImageList 
appena creato. 

6 Creare le voci di menu e di sottomenu come precedentemente descritto. 

7 Selezionare la voce di menu per la quale si desidera un'immagine nell'Object 
Inspector e impostare la proprieta Imagelndex al corrispondente numero 
dell'immagine neWImageList (il valore predefinito per Imagelndex e -1, che non 
visualizza alcuna immagine). 

Usare immagini 16 per 16 pixel per una visualizzazione corretta nel menu. Anche se e 
possibile usare altre dimensioni, quando si usano immagini piu grandi o piu piccole 
potrebbero nascere problemi di allineamento e di coerenza. 

Visualizzazione del menu 

In fase di progettazione, e possibile visualizzare il menu nella scheda senza prima 
eseguire il codice del programma. (I menu del componente a comparsa sono visibili 
nella scheda in fase di progettazione, ma cio non succede per gli stessi menu a 
comparsa. Usare il Menu Designer per visualizzare un menu a comparsa in fase di 
progettazione.) 

Per visualizzare il menu: 

1 Se la scheda e visibile, fare clic sulla scheda, o dal menu View, scegliere la scheda 
di cui si vuole visualizzare il menu. 

2 Se la scheda ha piu di un menu, selezionare il menu desiderato dall'elenco a 
discesa della proprieta Menu della scheda. 

II menu appare nella scheda esattamente come apparira quando il programma 
viene eseguito. 

Editing delle voci di menu nell'Object Inspector 



Questa sezione ha trattato come impostare alcune proprieta per le voci di menu-per 
esempio, le proprieta Name e Caption-usando il Menu Designer. 

La sezione ha anche descritto come impostare le proprieta di una voce di menu, come 
Shortcut, direttamente nell'Object Inspector, proprio come si farebbe per qualsiasi 
componente selezionato nella scheda. 

Quando si modifica una voce di menu usando il Menu Designer, le sue proprieta 
vengono ancora visualizzate nell'Object Inspector. Si puo passare il fuoco all'Object 
Inspector e continuare li l'editing delle proprieta della voce di menu. Oppure si puo 
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selezionare la voce di menu dal Component list nell'Object Inspector e modificarne le 
proprieta senza aprire sempre il Menu Designer. 

Per chiudere il Menu Designer e continuare la modifica delle voci di menu: 

1 Passare il fuoco dalla finestra Menu Designer all'Object Inspector facendo clic 
sulla pagina Properties dell'Object Inspector. 

2 Chiudere il Menu Designer coma al solito. 

II fuoco rimane nell'Object Inspector, dove e possibile continuare l'editing delle 
proprieta per la voce di menu selezionata. Per modificare un'altra voce di menu, 
selezionarla dal Component list. 

Uso del menu contestuale Menu Designer 

II menu contestuale di Menu Designer fornisce un rapido accesso ai comandi piu 
usati del Menu Designer, e alle opzioni relative ai modelli di menu. Per ulteriori 
informazioni sui modelli di menu, consultare "Uso dei modelli di menu" a 
pagina 8-41.) 

Per visualizzare il menu contestuale, fare clic con il tasto destro sulla finestra Menu 
Designer, o premere Alt+FW mentre il cursore si trova nella finestra. 

I comandi del menu contestuale 

La seguente tabella riporta i comandi del menu contestuale Menu Designer. 

Tabella 8.5 Comandi del menu contestuale Menu Designer 
Comando Azione 

Insert Inserisce un placeholder sopra o a sinistra del cursore. 

Delete Cancella la voce di menu selezionata (e tutti i suoi sottoelementi, se ne 

esistono). 

Create Submenu Crea un placeholder a un livello annidato e aggiunge una freccia alia 

destra della voce di menu selezionata. 

Select Menu Apre un elenco di menu nella scheda corrente. Facendo doppio clic su un 

nome di menu si apre la finestra designer per il menu. 

Save As Template Apre la finestra di dialogo Save Template, dove e possibile salvare un 
menu che potrebbe essere utile in future 

Insert From Apre la finestra di dialogo Insert Template, dove e possibile selezionare 

Template un modello da riutilizzare. 

Delete Templates Apre la finestra di dialogo Delete Templates, dove e possibile cancellare 
un qualsiasi modello esistente. 

Insert From Apre la finestra di dialogo Insert Menu from file Resource, dove e 

Resource possibile scegliere un file .rc oppure .mnu da aprire nella scheda corrente. 

Passaggio da un menu all'altro in fase di progettazione 

Se per la scheda occorre creare molti menu, si pud usare il menu contestuale Menu 
Designer o l'Object Inspector per selezionare e spostarsi facilmente dall'uno all'altro. 
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Per usare il menu contestuale per passare da un menu all'altro di una scheda: 
1 Fare clic destro nel Menu Designer e scegliere Select Menu. 

Viene visualizzata la finestra di dialogo Select Menu. 

Figura 8.8 Finestra di dialogo Select Menu 
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Questa finestra di dialogo elenca tutti i menu associati alia scheda il cui menu e 
attualmente aperto nel Menu Designer. 

2 Dall'elenco della finestra di dialogo Select Menu, scegliere il menu da visualizzare 
o modificare. 

Per usare Object Inspector to switch between menus in a form: 

1 Passare il fuoco sulla scheda da cui scegliere i menu. 

2 Dal Component list, selezionare il menu da modificare. 

3 Sulla pagina Properties dell'Object Inspector, selezionare la proprieta Items per 
questo menu, e quindi fare clic sul pulsante ellissi o doppio clic su [Menu]. 

Uso dei modelli di menu 



C++Builder fornisce molti menu gia progettati, o modelli di menu, che contengono i 
comandi usati piu frequentemente.E possibile usare questi menu nella applicazioni 
senza modificarli (a parte la scrittura del codice), o come punto di partenza, 
personalizzandoli come si farebbe con un proprio menu progettato in precedenza. I 
modelli di menu non contengono qualsiasi codice di gestore di evento. 

I modelli di menu forniti con C++Builder sono memorizzati nella sottodirectory BIN 
di un'installazione predefinita. Questi file hanno estensione .dmt (modelli di menu di 
C++Builder. 

Inoltre, e possibile salvare un modello di qualsiasi menu progettato usando Menu 
Designer. Dopo aver salvato un menu come modello, e possibile usarlo come 
qualsiasi menu gia progettato. Quando un particolare modello di menu non serve 
piu, e possibile cancellarlo dall'elenco. 

Per aggiungere un modello di menu all'applicazione: 

1 Fare clic con il tasto destro sul Menu Designer e scegliere Insert From Template. 



Sviluppo dell'interfaccia utente dell'applicazione 8-41 



Creazione e gestione dei menu 

(Se non ci sono modelli, l'opzione Insert From Template nel menu contestuale 
appare attenuata.) 

Viene aperta la finestra di dialogo Insert Template, con un elenco di modelli di 
menu disponibili. 

Figura 8.9 Esempio di finestra di dialogo Insert Template per i menu 
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2 Selezionare il modello di menu da inserire, quindi premere Invio o scegliere OK. 

Questa operazione inserisce il menu nella scheda alia posizione del cursore. Per 
esempio, se il cursore e su una voce di menu di un elenco, il modello di menu 
viene inserito sopra la voce selezionata. Se il cursore e sulla barra dei menu, il 
modello viene inserito a sinistra del cursore. 

Per cancellare un modello di menu: 

1 Fare clic con il tasto destro sul Menu Designer e scegliere Delete Templates. 

(Se non ci sono modelli, l'opzione Delete Templates del menu contestuale appare 
attenuata.) 

Viene aperta la finestra di dialogo Delete Templates, con un elenco di modelli 
disponibili. 

2 Selezionare il modello di menu da cancellare, e premere Del. 
C++Builder cancella il modello dall'elenco e dal disco rigido. 

Salvataggio di un menu come modello 



Qualsiasi menu progettato puo essere salvato come modello, in modo da poterlo di 
nuovo. I modelli di menu possono essere usati per fornire alle applicazioni un 
aspetto armonioso, o come punto di partenza per ulteriori personalizzazioni. 

I modelli di menu salvati vengono memorizzati nella sottodirectory BIN come file 
.dmt. 

Per salvare un menu come modello: 
1 Progettare il menu da riutilizzare. 
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Questo menu pud contenere tutte le voci, i comandi e i sottomenu preferiti; tutto 
cio che si trova nella finestra Menu Designer attiva verra salvato come menu 
riutilizzabile. 

2 Fare clic con il tasto destro sul Menu Designer e scegliere Save As Template. 
Viene visualizzata la finestra di dialogo Save Template. 
Figura 8.10 Finestra di dialogo Save Template per menu 
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3 Nella casella di modifica Template Description, scrivere una breve descrizione per 
questo menu, e quindi scegliere OK. 

La finestra di dialogo Save Template si chiude, salvando il progetto del menu e 
ritornando alia finestra Menu Designer. 

La descrizione immessa viene visualizzata solo nelle finestre di dialogo Save 
Template, Insert Template e Delete Templates. Non e collegata alia proprieta Name o 
Caption per il menu. 

Convenzioni per I'assegnazione dei nomi delle voci di menu e dei gestori di 
evento di un modello 

Quando si salva un menu come modello, C++Builder non salva la sua proprieta 
Name, poiche ogni menu deve avere un nome caratteristico all'interno del campo 
d'azione del suo proprietario (la scheda). Tuttavia, quando in una scheda viene 
inserito il menu come modello usando il Menu Designer, allora C++Builder genera 
nuovi nomi per il menu stesso e per tutte le sue voci. 

Per esempio, si supponga di salvare un menu File come modello. Nel menu originale, 
questo menu e stato chiamato MyFile. Se tale menu viene inserito come modello in un 
nuovo menu, C++Builder gli assegna il nome Filel. Se il menu viene inserito in un 
menu con una voce di menu chiamata Filel, C++Builder gli assegna il nome Filel. 

C++Builder non salva neanche tutti i gestori di evento OnClick associata a un menu 
salvato come modello, poiche non c'e alcun modo per verificare se il codice e valido 
nella nuova scheda. Quando viene generato un nuovo gestore di evento per la voce 
di menu di un modello, C++Builder genera ancora il nome del gestore di evento. 
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E possibile associare facilmente le voci del modello di menu ai gestori di evento 
OnClick esistenti nella scheda. 

Manipolazione delle voci di menu in fase di esecuzione 



Qualche volta, potrebbe essere necessario aggiungere delle voci di menu a una 
struttura di menu esistente mentre l'applicazione e in esecuzione, in modo da fornire 
ulteriori informazioni o opzioni all'utente. E possibile inserire una voce di menu 
usando il metodo Add o Insert della voce di menu, o in alternativa nascondere e 
mostrare le voci di un menu cambiando la loro proprieta Visible. La proprieta Visible 
determina se la voce viene visualizzata nel menu. Per attenuare una voce di menu 
senza nasconderla, usare la proprieta Enabled. 

Per esempi che usano le proprieta Visible e Enabled della voce di menu, consultare 
"Disattivazione delle voci di menu" a pagina 6-10. 

Nelle applicazioni MDI (Multiple Document Interface) e OLE (Object Linking and 
Embedding), e possibile anche fondere le voci contenute in una barra di menu 
esistente. La seguente sezione tratta questo argomento in dettaglio. 

Fusione dei menu 



Per le applicazioni MDI, come un'applicazione di esempio di editor di testi, e per le 
applicazioni client OLE, il menu principale dell'applicazione deve essere in grado di 
ricevere voci di menu da un'altra scheda o dall'oggetto server OLE. Spesso, cio viene 
chiamato/wszone di menu. E bene ricordare che la tecnologia OLE e utilizzabile solo in 
applicazioni Windows e non e disponibile per lo sviluppo di applicazioni 
multip iattaf or ma . 

I menu da fondere vengono preparati specificando i valori di due proprieta: 

• Menu, una proprieta della scheda 

• Grouplndex, una proprieta delle voci del menu 

Specifica del menu attivo: proprieta Menu 

La proprieta Menu specifica il menu attivo per la scheda. Le operazioni per la fusione 
dei menu valgono solo per il menu attivo. Se la scheda contiene piu di un 
componente menu, e possibile cambiare il menu attivo in fase di esecuzione 
impostando la proprieta Menu nel codice. Per esempio, 

Forml->Menu = SecondMenu; 

Determinazione dell'ordine delle voci di menu fuse: proprieta Grouplndex 

La proprieta Grouplndex determina l'ordine in cui le voci di menu fuse appaiono nella 
barra dei menu condivisa. Le voci di menu della fusione possono sostituire quelle 
sulla barra del menu principale, o essere mischiate. 

II valore predefinito per Grouplndex e 0. Quando si specifica un valore per Grouplndex 
si devono applicare diverse regole: 
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• I numeri piu bassi appaiono prima (piu a sinistra) nel menu. 

Per esempio, impostare la proprieta Grouplndex a (zero) per un menu che debba 
essere sempre il primo a sinistra, come un menu File. Analogamente, specificare 
un numero alto (non necessariamente in sequenza) per un menu che debba essere 
sempre il primo a destra, come un menu Help. 

• Per sostituire le voci del menu principale, dare alle voci sul menu figlio lo stesso 
valore Grouplndex. 

Questa regola e applicabile ai raggruppamenti e alle singole voci. Per esempio, se 
la scheda principale ha una voce di menu Edit con un valore Grouplndex di 1, e 
possibile sostituirla con una o piu voci dal menu della scheda figlia dando anche a 
questa un valore Grouplndex di 1. 

Fornendo alle stesse voci del menu figlio lo stesso valore Grouplndex si tiene il loro 
ordine intatto quando vengono fuse nel menu principale. 

• Per inserire le voci senza sostituire quelle del menu principale, lasciare spazio 
nell'intervallo numerico delle voci del menu principale e "inserire" i numeri dalla 
scheda figlia. 

Per esempio, numerare le voci del menu principale e 5, e inserire le voci del 
menu figlio numerandole 1, 2, 3 e 4. 

Importazione dei file risorsa 



C++Builder supporta menu costruiti con altre applicazioni, purche siano nel formato 
file risorsa standard (.RC) di Windows. Tali menu possono essere importati 
direttamente nel progetto C++Builder, risparmiando il tempo e la fatica di costruire 
di nuovo i menu che sono stati creati altrove. 

Per caricare i file menu .RC esistenti: 

1 Nel Menu Designer, collocare il cursore nel punto in cui far apparire il menu. 

II menu importato puo far parte di un menu in costruzione, o essere un menu 
completo. 

2 Fare clic con il tasto destro e scegliere Insert From Resource. 
Viene visualizzata la finestra di dialogo Insert Menu From Resource. 

3 Nella finestra di dialogo, selezionare il file risorsa da caricare e scegliere OK. 

II menu appare nella finestra Menu Designer. 

Se il file risorsa contiene piu di un menu, occorre prima salvare ciascun menu come 
un file risorsa distinto prima di importarlo. 

Progettazione di barre strumenti e di coolbar 



Una barra strumenti e un pannello, solitamente nella parte superiore di una scheda 
(sotto la barra dei menu), che contiene pulsanti e altri controlli. Una coolbar (chiamata 
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anche rebar) e una particolare barra strumenti che visualizza i controlli su bande 
mobili e ridimensionabili. Se vi sono piu pannelli allineati al bordo superiore della 
scheda, essi vengono impilati in verticale, in base alia sequenza con cui sono stati 
aggiunti. 

L^j^ Le coolbar non sono disponibili in CLX per applicazioni multipiattaforma. 

' — — -J Su una barra strumenti possono essere messi controlli di qualsiasi tipo. Oltre ai 
pulsanti, potrebbe essere opportuno mettere griglie per l'uso dei colori, barre di 
scorrimento, etichette, e cosi via. 

Esistono molti modi per aggiungere una barra strumenti a una scheda: 

• Collocare un pannello (TP and) sulla scheda e aggiungervi i controlli (di solito 
pulsanti di scelta rapida). 

• Usare un componente barra strumenti (TToolBar) invece di TPanel, e aggiungervi i 
controlli. TToolBar gestisce i pulsanti e altri controlli, sistemandoli in righe e 
regolandone automaticamente dimensioni e posizioni. Se sulla barra strumenti 
vengono usati controlli pulsante di strumento (TToolButton), TToolBar facilita il 
raggruppamento dei pulsanti per f unzione e fornisce altre opzioni di 
visualizzazione. 

• Usare un componente coolbar (TCoolBar) e aggiungervi i controlli. La coolbar 
visualizza i controlli su bande mobili e ridimensionabili indipendenti. 

II modo in cui implementare la barra strumenti dipende dall'applicazione. II 
vantaggio di usare il componente Panel sta nel fatto che si ha il controllo totale 
dell'aspetto della barra strumenti. 

Usando componenti barra strumenti e coolbar, si garantisce all'applicazione di avere 
l'aspetto di un'applicazione Windows, poiche vengono usati i controlli Windows 
nativi. Se questi controlli del sistema operativo in futuro cambiano, anche 
l'applicazione potrebbe cambiarli. Inoltre, dal momento che la barra strumenti e la 
coolbar fa affidamento sui componenti standard di Windows, l'applicazione richiede 
COMCTL32.DLL. Le barre strumenti e le coolbar non vengono supportate dalle 
applicazioni WinNT 3.51. 

Nelle sezioni seguenti viene descritta la procedura per: 

• Aggiungere una barra strumenti e i corrispondenti controlli pulsante di scelta 
rapida usando il componente barra strumenti. 

• Aggiungere una barra strumenti e i corrispondenti controlli pulsante strumento 
usando il componente barra strumenti. 

• Aggiungere una coolbar usando il componente coolbar. 

• Rispondere ai clic. 

• Aggiungere barre strumenti e coolbar nascoste. 

• Nascondere e mostrare barre strumenti e coolbar. 
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Aggiunta di una barra strumenti usando un componente panel 



Per aggiungere una barra strumenti a una scheda usando il componente panel: 

1 Aggiungere alia scheda un componente panel (dalla pagina Standard della 
Component palette). 

2 Impostare la proprieta Align del pannello a alTop. Quando e allineato alia parte 
superiore della scheda, il pannello conserva l'altezza, ma adegua la sua larghezza 
a quella dell'area client della scheda, anche se la finestra cambia dimensioni. 

3 Aggiungere i pulsanti di scelta rapida o altri controlli al pannello. 

I pulsanti di scelta rapida sono progettati per lavorare sui pannelli della barra 
strumenti. Un pulsante di scelta rapida, normalmente, non ha alcun caption, ma solo 
un piccolo grafico (chiamato glyph), che rappresenta la funzione del pulsante. 

I pulsanti di scelta rapida hanno tre possibili modi di funzionamento. Essi possono 

• Agire come normali pulsanti a pressione 

• Attivare e disattivare quando vi si fa clic sopra 

• Agire come un insieme di pulsanti radio 

Per implementare i pulsanti di scelta rapida sulle barre strumenti: 

• Aggiungere un pulsante di scelta rapida a un pannello della barra strumenti. 

• Assegnare un glyph al pulsante di scelta rapida. 

• Impostare la condizione iniziale di un pulsante di scelta rapida. 

• Creare un gruppo di pulsanti di scelta rapida. 

• Consentire la commutazione dei pulsanti. 

Aggiunta di un pulsante di scelta rapida a un pannello 

Per aggiungere un pulsante di scelta rapida a un pannello della barra strumenti, 
collocare il componente pulsante di scelta rapida (dalla pagina Additional della 
Component palette) sul pannello. 

II pannello, e non la scheda, "possiede" il pulsante di scelta rapida, in modo che 
spostando o nascondendo il pannello si sposta o si nasconde anche il pulsante di 
scelta rapida. 

L'altezza predefinita del pannello e 41, mentre quella dei pulsanti di scelta rapida e 
25. Se la proprieta Top di ciascun pulsante viene impostata a 8, essi verranno centrati 
verticalmente. L'impostazione predefinita della griglia blocca automaticamente il 
pulsante di scelta rapida in quella posizione verticale. 

Assegnazione del glifo a un pulsante di scelta rapida 

Ogni pulsante di scelta rapida ha bisogno di un'immagine grafica, detta anche glifo, 
per indicare all'utente la funzione svolta. Se viene fornita solo un'immagine, il 
pulsante di scelta rapida manipola quell'immagine per indicare che e stato premuto, 
non premuto, selezionato o disattivato. Se si preferisce, e possibile fornire anche 
specifiche immagini distinte per ciascuno stato. 
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Normalmente, i glifi vengono assegnati ai pulsanti di scelta rapida in fase di 
progettazione, anche se e possibile assegnare glifi differenti in fase di esecuzione. 

Per assegnare un glifo a un pulsante di scelta rapida in fase di progettazione: 

1 Selezionare il pulsante di scelta rapida. 

2 Nell'Object Inspector, selezionare la proprieta Glyph. 

3 Fare doppio clic sulla colonna Value a fianco di Glyph per aprire il Picture Editor e 
selezionare la bitmap desiderate 

Impostazione della condizione iniziale di un pulsante di scelta rapida 

I pulsanti di scelta rapida sfruttano il proprio aspetto per dare all'utente indizi 
relativi al loro stato e alia loro funzione. Poiche non hanno alcuna etichetta, e 
importante usare le parti visuali corrette per aiutare gli utenti. 

La Tabella 8.6 elenca alcune azioni che e possibile impostare per cambiare l'aspetto di 
un pulsante di scelta rapida: 



Tabella 8.6 Impostazione dell'aspetto di pulsanti scelta rapid a 



Per fare in modo che un pulsante di 




scelta rapida: 


Nella barra strumenti, impostare: 


Appaia premuto 


La proprieta Grouplndex a un valore diverso da zero e la 




sua proprieta Down a true. 


Appaia disattivato 


La proprieta Enabled a false. 


Abbia un margine sinistra 


La proprieta Indent a una valore maggiore di 0. 



Se l'applicazione ha uno strumento di disegno predefinito, essere certi che il suo 
pulsante sulla barra strumenti e premuto quando l'applicazione viene avviata. Per 
eseguire questa operazione, impostare la sua proprieta Grouplndex a un valore 
diverso da zero e la sua proprieta Down a true. 



Creazione di un gruppo di pulsanti di scelta rapida 

Spesso, una serie di pulsanti di scelta rapida rappresenta un insieme di scelte che si 
escludono a vicenda. In questo caso, occorre riunire i pulsanti in un gruppo, in modo 
che il clic su un qualsiasi pulsante del gruppo obblighi gli altri pulsanti a risalire. 

Per associare un qualsiasi numero di pulsanti di scelta rapida in un gruppo, 
assegnare lo stesso numero a ciascuna proprieta Grouplndex del pulsante di scelta 
rapida. 

II modo piu facile per compiere questa operazione e quello di selezionare tutti i 
pulsanti desiderati nel gruppo, e, con l'intero gruppo selezionato, impostare 
Grouplndex a un valore caratteristico. 

Come consentire la commutazione dei pulsanti 

Qualche volta, si vuole avere la possibility di fare clic su un pulsante gia premuto di 
un gruppo e riportarlo su, non lasciando nel gruppo alcun pulsante premuto. Un tale 
pulsante viene chiamato commutatore. Usare AllowAUUp per creare un pulsante di 
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gruppo che agisce come un commutatore: facendo clic su esso una prima volta, 
rimane giu; facendo clic di nuovo, ritorna su. 

Perche un pulsante di scelta rapida di gruppo diventi un commutatore, impostare la 
sua proprieta AllowAUUp a true. 

Impostando AllowAUUp a true per tutti i pulsanti di scelta rapida di un gruppo, si 
imposta automaticamente lo stesso valore di proprieta per tutti i pulsanti del gruppo. 
Cio consente al gruppo di agire come un normale gruppo, con un solo pulsante 
premuto alia volta, ma consente anche ai pulsanti di essere contemporaneamente 
tutti su. 

Aggiunta di una barra strumenti usando il relativo componente 



II componente barra strumenti (TToolBar) offre caratteristiche di gestione e di 
visualizzazione dei pulsanti che i componenti pannello non hanno. Per aggiungere 
una barra strumenti a una scheda usando questo componente: 

1 Aggiungere alia scheda un componente barra strumenti (dalla pagina Win32 della 
Component palette). La barra strumenti viene allineata automaticamente alia 
parte superiore della scheda. 

2 Aggiungere alia barra i pulsanti strumento o altri controlli. 

I pulsanti strumento sono progettati per lavorare sui componenti barra strumenti. 
Come i pulsanti di scelta rapida, i pulsanti strumento possono: 

• Agire come normali pulsanti a pressione. 

• Attivare e disattivare quando vi si fa clic sopra. 

• Agire come un insieme di pulsanti radio. 

Per implementare i pulsanti strumento su una barra strumenti: 

• Aggiungere un pulsante strumento 

• Assegnare le immagini ai pulsanti strumento 

• Impostare l'aspetto dei pulsanti strumento 

• Creare un gruppo di pulsanti strumento 

• Consentire la commutazione di pulsanti strumento 

Aggiunta di un pulsante strumento 

Per aggiungere un pulsante strumento a una barra strumenti, fare clic con il tasto 
destro sulla barra strumenti e scegliere New Button. 

La barra strumenti "possiede" il pulsante strumento, cosi che, spostando o 
nascondendo la barra strumenti, si sposta o si nasconde anche il pulsante. Inoltre, 
tutti i pulsanti strumento sulla barra strumenti mantengono automaticamente 
l'altezza e la larghezza. Sulla barra strumenti e possibile rilasciare altri controlli dalla 
Component palette, e manterranno automaticamente un'altezza uniforme. I controlli, 
inoltre, vanno automaticamente a capo e iniziano una nuova riga quando la 
dimensione orizzontale della barra strumenti non e sufficiente a contenerli. 
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Assegnazione di immagini ai pulsanti strumento 

Ogni pulsante strumento ha una proprieta Imagelndex che determina quale immagine 
appare su di esso in fase di esecuzione. Se al pulsante strumento viene fornita solo 
un'immagine, il pulsante manipola quell'immagine per indicare che il pulsante e 
disattivato. Per assegnare le immagini ai pulsanti strumento in fase di progettazione: 

1 Selezionare la barra strumenti sulla quale devono apparire i pulsanti. 

2 Nell'Object Inspector, assegnare un oggetto TImageList alia proprieta Images della 
barra strumenti. Un elenco di immagini e una raccolta di icone o bitmap con le 
stesse dimensioni. 

3 Selezionare un pulsante strumento. 

4 Nell'Object Inspector, assegnare un intero alia proprieta Imagelndex del pulsante 
strumento che corrisponde all'immagine dell'elenco da assegnare al pulsante. 

E possibile specificare anche immagini distinte che appaiono sui pulsanti strumento 
quando vengono disattivati e quando sono sotto il puntatore del mouse. Per eseguire 
questa operazione, assegnare immagini distinte alle proprieta Disabledlmages e 
Hotlmages della barra strumenti. 

Impostazione dell'aspetto di un pulsante strumento e delle condizioni iniziali 

La Tabella 8.7 elenca alcune azioni che e possibile impostare per cambiare l'aspetto di 
un pulsante strumento: 

Tabella 8.7 Impostazione dell'aspetto di pulsanti strumento 

Per fare in modo che un pulsante 
strumento: 



Appaia premuta 

Appaia disattivato 

Abbia un margine sinistra 

Appaia con i bordi "pop-up", 
rendendo percio la barra strumenti 
trasparente 



Nella barra strumenti, impostare 

(La proprieta Style (su un pulsante strumento) a tbsChecke 
e la proprieta Down a true. 

La proprieta Enabled a false. 

La proprieta Indent a una valore maggiore di 0. 

La proprieta Flat a true. 



L'uso della proprieta Flat di TToolBar richiede la versione 4.70 o successive di 
COMCTL32.DLL. 

Per forzare una nuova riga di controlli dopo un determinato pulsante, strumento, 
selezionare il pulsante strumento che deve apparire per ultimo nella riga e impostare 
la sua proprieta Wrap a true. 

Per disattivare la caratteristica auto-wrap di una barra strumenti, impostare la 
proprieta Wrapable della barra strumenti a false. 

Creazione di gruppi di pulsanti strumento 

Per creare un gruppo di pulsanti strumento, selezionare i pulsanti da associare e 
impostare la loro proprieta Style a tbsCheck; quindi impostare la loro proprieta 
Grouped a true. La selezione di un pulsante strumento di gruppo obbliga gli altri 
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pulsanti del gruppo a pop up, che e un utile modo di rappresentare un insieme di 
scelte che si escludono a vicenda. 

Una qualsiasi sequenza ininterrotta di pulsanti strumento adiacenti con Style 
impostata a tbsCheck e Grouped impostata a true forma un singolo gruppo. Per 
spezzare un gruppo di pulsanti strumento, separare i pulsanti con un qualsiasi: 

• Pulsante strumento la cui proprieta Grouped e false. 

• Pulsante strumento la cui proprieta Style non e impostata a tbsCheck. Per creare 
spazi o divisioni sulla barra strumenti, aggiungere un pulsante strumento la cui 
proprieta Style e tbsSeparator o tbsDivider. 

• Un altro controllo che non sia un pulsante strumento. 

Come consentire pulsanti strumento commutati 

Usare AllowAllUp per creare un pulsante strumento di gruppo che agisce come un 
commutatore: facendo clic su esso una prima volta, rimane giu; facendo clic di 
nuovo, ritorna su.Perche un pulsante strumento di gruppo diventi un commutatore, 
impostare la sua proprieta AllowAllUp a true. 

Come i pulsanti di scelta rapida, impostando AllowAllUp a true per tutti i pulsanti 
strumento di un gruppo, si imposta automaticamente lo stesso valore di proprieta 
per tutti i pulsanti del gruppo. 

Aggiunta di un componente coolbar 



II componente TCoolBar richiede la versione 4.70 o successiva di COMCTL32.DLL e 
non e disponibile in CLX. 

II componente coolbar (TCoolBar) - detto anche rebar - visualizza controlli con 
finestra su bande mobili e ridimensionabili in modo indipendente. L'utente puo 
posizionare le bande trascinando i grip di ridimensionamento sul lato sinistro di 
ciascuna banda. 

Per aggiungere una coolbar a una scheda in un'applicazione Window: 

1 Aggiungere alia scheda un componente coolbar (dalla pagina Win32 della 
Component palette). La coolbar viene allineata automaticamente alia parte 
superiore della scheda. 

2 Aggiungere alia barra i controlli windowed dalla Component palette. 

Solo i componenti della VCL che discendono da TWinControl sono controlli con 
finestra. E possibile aggiungere alia coolbar controlli grafici, come etichette o 
pulsanti, ma non appariranno su bande distinte. 
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Impostazione dell'aspetto della coolbar 

II componente coolbar offre molte utili opzioni di configurazione. La Tabella 8.8 
elenca alcune azioni che e possibile impostare per cambiare l'aspetto di un pulsante 
strumento: 

Tabella 8.8 Impostazione dell'aspetto di un pulsante cool 
Per fare in modo che la coolbar: Nella barra strumenti, impostare: 

Venga ridimensionata automaticamente La proprieta AutoSize a true, 
per alloggiare le bande che contiene 

Mantenga le bande a un'altezza 
uniforme 

Venga orientata verticalmente invece 
che orizzontalmente 

Impedisca alle proprieta Text delle 
bande la visualizzazione in fase di 
esecuzione 

Rimuova il bordo che la circonda 

Impedisca agli utenti di cambiare 
l'ordine delle bande in fase di 
esecuzione. (L'utente pud sempre 
spostare e ridimensionare le bande.) 

Crei un'immagine per lo sfondo della 
coolbar 

Scelga un elenco di immagini da 
visualizzare a sinistra di qualsiasi banda 



Per assegnare immagini alle singole bande, selezionare la coolbar e fare doppio clic 
sulla proprieta Bands nell'Object Inspector. Quindi selezionare una banda e assegnare 
un valore alia sua proprieta Imagelndex. 

Risposta ai clic 



Quando l'utente fa clic su un controllo, come un pulsante su una barra strumenti, 
l'applicazione genera un evento OnCHck a cui e possibile rispondere con un gestore 
di evento. Poiche OnClick e l'evento predefinito dei pulsanti, e possibile generare uno 
scheletro di gestore di evento facendo doppio clic sul pulsante in fase di 
progettazione. 

Assegnazione di un menu a un pulsante strumento 

Se viene usata una barra strumenti (TToolBar) con pulsanti strumento (TToolButton), e 
possibile associare un menu a uno specifico pulsante: 

1 Selezionare il pulsante strumento. 

2 Nell'Object Inspector, assegnare un menu a comparsa (TPopupMenu) alia proprieta 
DropDoivnMenu del pulsante strumento. 



La proprieta FixedSize a true. 

La proprieta Vertical a true. Questa operazione cambia 
l'effetto della proprieta FixedSize. 

La proprieta ShowText a false. Ciascuna banda di una 
coolbar ha una sua proprieta Text. 

La proprieta BandBorderStyle a bsNone. 
FixedOrder a true. 



La proprieta Bitmap all'oggetto TBitmap. 
La proprieta Images all'oggetto TImageList. 
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Se la proprieta AutoPopup del menu e impostata a true, apparira automaticamente 
quando il pulsante viene premuto. 

Aggiunta di barre strumenti nascoste 



Le barre strumenti non devono essere visibili tutte le volte. Infatti, spesso e comodo 
avere a disposizione un gran numero di barre strumenti, ma mostrarle solo quando 
l'utente desidera usarle. Altrettanto spesso, quindi, viene creata una scheda che ha 
molte barre strumenti, ma tutte o in parte nascoste. 

Per creare una barra strumenti nascosta: 

1 Aggiungere alia scheda un componente barra strumenti, coolbar o pannello. 

2 Impostare la proprieta Visible del componente a false. 

Anche se la barra strumenti rimane visibile in fase di progettazione in modo da 
poterla modificare, rimane nascosta in fase di esecuzione finche l'applicazione non la 
rende specif icamente visibile. 

Come nascondere e mostrare le barre strumenti 



Spesso, e opportuno che un'applicazione abbia barre strumenti multiple, ma non si 
vuole ingombrare la scheda visualizzandole tutte insieme. Oppure, si puo lasciare 
agli utenti la possibility di decidere se visualizzare le barre strumenti. Come tutti i 
componenti, le barre strumenti possono essere mostrate o nascoste, secondo le 
necessita, in fase di esecuzione. 

Per nascondere o mostrare una barra strumenti in fase di esecuzione, impostare la 
sua proprieta Visible, rispettivamente, a false o true. Normalmente, questa 
operazione viene eseguita in risposta a particolari eventi dell'utente o a modifiche nel 
modo operativo dell'applicazione. Per eseguire questa operazione, normalmente c'e 
un pulsante close su ciascuna barra strumenti. Quando l'utente fa clic su quel 
pulsante, l'applicazione nasconde la corrispondente barra strumenti. 

E anche possibile fornire strumenti per la commutazione della barra strumenti. nel 
seguente esempio, una barra strumenti di penne viene commutata da un pulsante 
sulla barra strumenti principale. Poiche ciascun clic preme o rilascia il pulsante, un 
gestore di evento OnClick puo mostrare o nascondere al barra strumenti Pen a 
seconda che il pulsante sia su o giu. 

void __fastcall TForml: :PenButtonClick(TObject *Sender) 

{ 

PenBar->Visible = PenButton->Down; 

} 
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Capitolo 




Tipi di controlli 

I controlli sono componenti visuali che aiutano a progettare l'interfaccia utente. 

Questo capitolo descrive i vari controlli che e possibile utilizzare, tra cui controlli di 
testo, controlli di input, pulsanti, controlli elenco, controlli di raggruppamento, 
controlli di visualizzazione, griglie, editor di valori di 'elenco e controlli grafici. 

Per la creazione di un controllo grafico consultare il Capitolo 54, "Creazione di un 
controllo grafico". Per sapere come implementare tali controlli vedere il Capitolo 6, 
"Uso dei controlli". 



Controlli di testo 



Molte applicazioni utilizzano controlli di testo per mostrare il testo all'utente. E 
possibile utilizzare: 

• Controlli di editing, che permettono all'utente di aggiungere testo. 



Utilizzare questo 
componente: 

TEdit 

TMemo 

TMaskEdit 

TRichEdit 



Per consentire all'utente di: 

Modificare una singola riga di testo. 
Modificare piu righe di testo. 

Immettere un testo in modo conforme a un particolare formato, come un 
codice postale oppure un numero di telefono. 

Modificare piu righe di testo utilizzando il formato rich text (solo per la 
VCL). 
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• Controlli per la visualizzazione del testo ed etichette, che non consentono 
all'utente di aggiungere testo: 



Utilizzare questo 




componente: 


Per consentire all'utente di: 


TTextBroivser 


Visualizzare un file di testo o una semplice pagina HTML che gli utenti 




possono scorrere. 


TTextVieiver 


Visualizzare un file di testo o una semplice pagina HTML. Gli utenti 




possono far scorrere la pagina o fare clic sui collegamenti per visualiz- 




zare altre pagine e immagini. 


TLCDNumber 


Visualizzare informazioni numeriche con un formato digitale. 


TLabel 


Visualizzare del testo in un controllo senza finestra. 


TStaticText 


Visualizzare testo in un controllo con finestra. 



Controlli di editing 



I controlli di editing mostrano del testo all'utente e gli consentono di immettere del 
testo. II tipo di controllo utilizzato a questo scopo dipende dalle dimensioni e dal 
formato delle informazioni. 

TEdit e TMaskEdit sono semplici controlli di testo che includono una casella di 
modifica per una singola linea di testo in cui e possibile inserire informazioni. 
Quando la casella di modifica riceve il fuoco, viene visualizzato un punto di 
inserimento lampeggiante. 

E possibile includere del testo nella casella di modifica assegnando un valore di 
stringa alia proprieta Text. L'aspetto del testo nella casella di modifica viene 
controllato assegnando dei valori alia proprieta Font. E possibile specificare il tipo di 
carattere, le dimensioni, il colore e gli attributi del carattere. Gli attributi influiscono 
su tutto il testo nella casella di modifica e non possono essere applicati a singoli 
caratteri. 

Una casella di modifica puo essere progettata in modo che modifichi le proprie 
dimensioni a seconda delle dimensioni del font utilizzato. L'operazione e possibile 
impostando la proprieta AutoSize a true. E possibile limitare il numero di caratteri 
che una casella di modifica puo contenere assegnando un valore alia proprieta 

MaxLength. 

TMaskEdit e uno speciale controllo per l'editing che convalida il testo immesso a 
fronte di una maschera che codifica i possibili formati validi che un testo puo 
assumere. La maschera puo anche formattare il testo che viene mostrato all'utente. 

TMemo e TRichEdit permettono all'utente di aggiungere diverse righe di testo. 
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Proprieta dei controlli di editing 



Di seguito sono elencate alcune importanti proprieta dei controlli testo: 
Tabella 9.1 Proprieta dei controlli di testo 



Proprieta 


Descrizione 


Text 


Determina il testo che viene visualizzato nel controllo casella di modifica o 
memo. 


Font 


Controlla gli attributi del testo scritto nel controllo casella di modifica o 
memo. 


AutoSize 


Permette alia casella di modifica di modificare dinamicamente la propria 
altezza a seconda del font attualmente selezionato. 


Readonly 


Specifica se all'utente e permesso modificare il testo. 


MaxLength 


Limita il numero di caratteri nei controlli di solo testo. 


SelText 


contiene la porzione di testo selezionata (evidenziata) al momento. 


SelStart, 
SelLength 


Indicano la posizione e la lunghezza della porzione di testo. 



Controlli memo e rich edit 

Entrambi i controlli TMemo e TRichEdit gestiscono piu linee di testo. 

I controlli rich edit sono inclusi solo nella VCL. 

TMemo e un altro tipo di casella di modifica che gestisce piu righe di testo. Le righe in 
un controllo memo possono estendersi oltre il margine destro della casella di 
modifica o possono passare automaticamente sulla riga successiva. L'avanzamento 
automatico alia riga successiva viene controllato utilizzando la proprieta WordWrap. 

II componente TRichedit e un controllo per campi memo che supporta il formato rich 
text, la stampa, la ricerca e il drag-and-drop di testo. Consente di specificare le 
proprieta per il tipo di carattere, l'allineamento, i fermi di tabulazione, i rientri e la 
numerazione. 

Oltre alle proprieta che tutti i controlli di editing possiedono, i controlli memo e rich 
edit includono altre proprieta, come le seguenti: 

• Alignment specifica come viene allineato il testo (a sinistra, a destra oppure al 
centro) nel componente. 

• La proprieta Text contiene il testo nel controllo. L'applicazione puo verificare se il 
testo e stato modificato controllando la proprieta Modified. 

• Lines contiene il testo come un elenco di stringhe. 

• OEMConvert determina se il testo viene convertito temporaneamente da ANSI a 
OEM al momento dell'immissione. Questa proprieta risulta utile per convalidare 
nomi di file (solo VCL). 

• WordWrap determina se il testo andra a capo automaticamente una volta raggiunto 
il margine destro. 

• WantReturns determina se l'utente puo inserire nel testo caratteri di ritorno a capo 
forzato. 

• WantTabs determina se l'utente puo inserire nel testo caratteri di tabulazione. 
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• AutoSelect determina se il testo viene selezionato automaticamente (evidenziato) 
non appena il controllo diviene attivo. 

In esecuzione, e possibile selezionare tutto il testo presente nel memo usando il 
metodo SelectAll. 

Controlli per la visualizzazione del testo (solo per la CLX) 



I controlli di visualizzazione testo mostrano il testo ma sono a sola lettura. 
TTextViewer agisce come un semplice visualizzatore in modo che gli utenti possano 
leggere e scorrere documenti. Con TTextBrowser, gli utenti possono anche fare clic sui 
collegamenti per navigare ad altri documenti e ad altre parti dello stesso documento. 
I documenti visitati sono memorizzati in una cronistoria, che puo essere percorsa 
utilizzando i metodi Backward, Forward e Home. TTextViewer e TTextBrowser sono 
utilizzati per visualizzare testo basato su HTML o per implementare un sistema di 
Guida basato su HTML. 

Oltre alle stesse proprieta di Ttext Viewer, TTextBrowser ha anche la proprieta Factory. 
Factory determina l'oggetto factory MIME utilizzato per determinare i tipi di file per 
le immagini incorporate. Ad esempio, e possibile associare le estensioni dei nome di 
file — come .txt, .html e .xml — con i tipi MIME e fare in modo che factory carichi 
questi dati nel controllo. 

Utilizzare la proprieta FileName per aggiungere un file di testo, come .html, che sara 
visualizzato nel controllo in esecuzione. 

Etichette 



Le etichette ( TLabel e TStaticText (solo per la VCL) visualizzano un testo e di solito 
sono poste accanto ad altri controlli. Si colloca un'etichetta su una scheda quando e 
necessario identificare o aggiungere un'annotazione a un altro componente, ad 
esempio una casella di testo, o quando si desidera aggiungere del testo a una scheda. 
II componente etichetta standard, TLabel, e un controllo non basato su finestra (non 
basato su widget in CLX), e pertanto non puo ricevere il fuoco; nel caso occorra 
un'etichetta con un handle di finestra, utilizzare invece TStaticText. 

Di seguito sono elencate alcune proprieta del componente Label: 

• Caption contiene la stringa del testo dell'etichetta. 

• Font, Color, e altre proprieta determinano l'aspetto dell'etichetta. Ogni etichetta 
puo utilizzare un solo tipo di carattere, dimensione e colore. 

• FocusControl collega l'etichetta a un altro controllo sulla scheda. Se Caption include 
un tasto acceleratore, quando l'utente preme tale tasto, il controllo specificato da 
FocusControl riceve fuoco. 

• ShowAccelChar determina se l'etichetta puo visualizzare un carattere acceleratore 
sottolineato. Se ShowAccelChar e true, qualsiasi carattere preceduto da un carattere 
"e commerciale" (&) appare sottolineato e attiva un tasto acceleratore. 



9-4 Guida alia programmazione 



Controlli specializzati per I'input 

• Transparent determina se gli elementi posti sotto l'etichetta (come gli elementi 
grafici) sono visibili o meno. 

Di solito le etichette servono per visualizzare del testo statico a sola lettura che non 
puo essere modificato dall'utente dell'applicazione. In fase di esecuzione, 
l'applicazione puo modificare il testo assegnando un nuovo valore alia proprieta 
Caption. Per aggiungere a una scheda un oggetto testo che l'utente possa far scorrere 
o modificare, utilizzare TEdit. 



Controlli specializzati per I'input 



I componenti seguenti forniscono modi aggiuntivi per catturare I'input. 



Utilizzare questo 
componente: 



Per consentire all'utente di: 



TScrollBar 
TTrackBar 

TUpDown 

THotKey 
TSpinEdit 



Selezionare valori in un intervallo continuo 

Selezionare valori in un intervallo continuo (impatto visivo piu efficace 
rispetto a una barra di scorrimento) 

Selezionare un valore da un controllo selettore associato a un compo- 
nente di modifica (solo VCL) 

Immettere sequenze di tastiera con Ctrl/ Shift/ Alt (solo VCL) 
Selezionare un valore da un widget con casella di selezione (solo CLX) 



Barre di scorrimento 



II componente scrollbar crea una barra di scorrimento che e possibile utilizzare per 
scorrere i contenuti di una finestra, di una scheda o di un altro controllo. Nel gestore 
di evento di OnScroll viene scritto il codice che determina come si comporta il 
controllo quando l'utente sposta il cursore della barra di scorrimento. 

II componente scrollbar non e utilizzato molto spesso, perche molti componenti 
visuali includono proprie barre di scorrimento e non richiedono scrittura di codice 
aggiuntivo. Per esempio, TForm ha le proprieta VertScrollBar e HorzScrollBar che 
consentono di configurare automaticamente le barre di scorrimento sulla scheda. Per 
creare una regione con scorrimento all'interno di una scheda utilizzare il componente 
TScrollBox. 

Barre di regolazione 



Un componente trackbar consente di impostare un valore intero in un intervallo 
continuo. Risulta utile per regolare proprieta quali colore, volume e luminosita. 
L'utente sposta l'indicatore a scorrimento trascinandolo in una particolare posizione 
oppure facendo clic all'interno della barra. 

• Utilizzare le proprieta Max e Min per impostare i limiti superiore e inferiore della 
barra di regolazione. 
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• Utilizzare SelEnd e SelStart per evidenziare un intervallo di selezione. Vedere la 
Figure 9.1. 

• La proprieta Orientation determina se la barra di regolazione e verticale oppure 
orizzontale. 

• Per impostazione predefinita, una barra di regolazione presenta una serie di 
tacche nella sua parte inferiore. Utilizzare la proprieta TickMarks per modificarne 
la posizione. Per controllare gli intervalli tra le tacche, utilizzare la proprieta 
TickStyle e il metodo SetTick. 

Figure 9.1 Tre viste del componente track bar 




• Position imposta una posizione predefinita per la barra di regolazione e ne traccia 
la posizione in esecuzione. 

• Per impostazione predefinita, l'utente pud spostare il cursore alia tacca precedente 
o successiva usando il tasti cursore Su e Giu. Impostare LineSize per modificare 
tale incremento. 

• Impostare PageSize per determinare il numero di tacche di spostamento 
conseguenti alia pressione dei tasti PgSu e PgGiu. 

Controlli up-down (solo VCL) 



Un controllo up-down (TUpDoivn) e formato di una coppia di pulsanti freccia che 
consentono agli utenti di modificare un valore intero mediante incrementi fissi. II 
valore corrente e dato dalla proprieta Position; l'incremento assunto per impostazione 
predefinita e pari a 1, ed e specificato dalla proprieta Increment. Utilizzare la 
proprieta Associate per associare al controllo di selezione un altro componente (come 
un controllo di editing. 

Controlli spin edit (solo CLX) 



Un controllo spin edit (casella di selezione) (TSpinEdit) viene anche definite come 
widget up-down, little arrows widget o pulsante a rotazione. Questo controllo 
permette all'utente di modificare un valore intero mediante incrementi fissi, o 
facendo clic sui pulsanti freccia, verso l'alto o verso il basso, per incrementare o 
decrementare il valore attualmente visualizzato oppure immettendo il valore 
direttamente nella casella di selezione. 

II valore corrente e contenuto nella proprieta Value ; l'incremento, che per 
impostazione predefinita e pari a 1, viene specificato mediante la proprieta Increment. 

Controlli Hot key (solo VCL) 



Utilizzare il componente hotkey (THotKey) per assegnare una scorciatoia di tastiera 
in grado di trasferire il fuoco a un qualsiasi controllo. La proprieta HotKey contiene la 
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Pulsanti e controlli simili 

combinazione di tasti corrente e la proprieta Modifiers determina quali tasti sono 
disponibile per HotKey. 

II componente hot key puo essere assegnato come proprieta ShortCut a una voce di 
menu. Quindi, quando un utente immette la combinazione di tasti specif icata dalle 
proprieta HotKey e Modifiers , Windows attiva la voce di menu. 

Controlli splitter 



Uno splitter (TSplitter) collocato tra controlli allineati consente all'utente di 
ridimensionare i controlli. Utilizzato con componenti quali pannelli e caselle di 
gruppo, gli splitter consentono di suddividere una scheda in diversi pannelli con piu 
controlli su ciascun pannello. 

Dopo avere collocato su una scheda un pannello o un altro controllo, aggiungere uno 
splitter con lo stesso allineamento del controllo. L'ultimo controllo dovrebbe essere 
allineato al client, in modo da occupare lo spazio rimante quando si ridimensionano 
gli altri componenti. Per esempio, e possibile collocare un pannello al margine 
sinistra di una scheda, impostare la sua proprieta Alignment a alLeft, quindi collocare 
uno splitter (anch'esso con allineamento alLeft) alia destra del pannello, e infine 
collocare un altro pannello (con allineamento alLeft oppure alClient) alia destra dello 
splitter. 

Impostare la proprieta MinSize per specificare la minima dimensione lasciata dallo 
splitter quando si ridimensiona il suo controllo con esso confinante. Impostare la 
proprieta Beveled a true per far assumere al bordo dello splitter un aspetto 
tridimensionale. 



Pulsanti e controlli simili 



Menu a parte, i pulsanti rappresentano il modo piu comune per attivare in 
un'applicazione un comando. C++Builder offre diversi controlli analoghi ai pulsanti: 



Utilizzare questo 

componente: Per fare cio: 

TButton Presentare scelte di comando su pulsanti con solo testo 

TBitBtn Presentare scelte di comando su pulsanti con testo e simboli grafici 

TSpeedButton Creare pulsanti raggruppati in una barra strumenti 

TCheckBox Presentare opzioni di tipo on/ off, si/ no 

TRadioButton Presentare una serie di scelte reciprocamente esclusive 

TToolBar Disporre pulsanti strumento ed altri controlli su piu righe e regolarne 

automaticamente dimensioni e posizioni 

TCoolBar Visualizzare una raccolta di controlli per finestra, all'interno di bande 

spostabili e dimensionabili (solo VCL) 
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Pulsanti e controlli simili 

Controlli pulsante 



L'utente fa clic con il mouse sui controlli pulsante per avviare azioni. I pulsanti 
hanno un'etichetta di testo che rappresenta l'azione. II testo viene specificato 
assegnando un valore stringa alia proprieta Caption. La maggior parte dei pulsanti 
puo essere selezionata anche premendo un tasto sulla tastiera, detto tasto di scelta 
rapida. La scorciatoia viene visualizzata sul pulsante come una lettera sottolineata. 

I controlli pulsante sono utilizzati per consentire agli utenti di iniziare un'azione 
facendo clic su di essi. E possibile assegnare un'azione a un componente TButton 
creando per esso un gestore di evento OnClick. Facendo doppio clic su un pulsante in 
fase di progettazione, si passa nel gestore dell'evento OnClick del pulsante nell'editor 
di Codice. 

• Impostare la proprieta Cancel a true se si desidera che il pulsante scateni il suo 
evento OnClick alia pressione del pulsante Esc. 

• Impostare la proprieta Default a true se si desidera che il tasto Invio scateni l'evento 
OnClick del pulsante. 

Pulsanti bitmap 



Un pulsante bitmap (BitBtn) e un controllo pulsante che presenta sulla sua superficie 
un'immagine bitmap. 

• Per scegliere una bitmap da assegnare al pulsante, impostare la proprieta Glyph. 

• Utilizzare la proprieta Kind per configurare automaticamente un pulsante con un 
simbolo e un comportamento predefiniti. 

• Per impostazione predefinita, il simbolo e posto alia sinistra di qualsiasi testo. Per 
spostarlo, utilizzare la proprieta Layout. 

• II simbolo e il testo vengono centrati automaticamente nel pulsante. Per spostarne 
la posizione, utilizzare la proprieta Margin. Margin determina il numero di pixel 
tra il bordo dell'immagine e il bordo del pulsante. 

• Per impostazione predefinita, l'immagine e il testo sono separati da 4 pixel. 
Utilizzare la proprieta Spacing per aumentare o diminuire la distanza. 

• I pulsanti bitmap possono avere 3 stati: su, giu e premuto. Impostare la proprieta 
NumGlyphs a 3 per mostrare una bitmap diversa per ciascuno stato. 

Pulsanti di scelta rapida 



I pulsanti di scelta rapida, che di solito hanno immagini sulla loro superficie, possono 
funzionare in gruppi. Di solito vengono utilizzati con pannelli per creare barre 
strumenti. 

• Per fare si che i pulsanti di scelta rapida si comportino come un gruppo, assegnare 
alia proprieta Grouplndex di tutti i pulsanti lo stesso valore diverso da zero. 

• Per impostazione predefinita, i pulsanti di scelta rapida appaiono nello stato non 
selezionato (non premuto). Per visualizzare inizialmente un pulsante di scelta 
rapida come selezionato (premuto), impostare la proprieta Down a true. 
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Pulsanti e controlli simili 



• Se la proprieta AllowAUUp e true, tutti i pulsanti di scelta rapida in un gruppo 
possono essere non selezionati. Impostare la proprieta AllowAUUp a false se si 
desidera che un gruppo di pulsanti agisca come un gruppo di pulsanti di opzione. 

Per ulteriori informazioni su pulsanti di accesso rapido, fare riferimento alle sezioni 
"Aggiunta di una barra strumenti usando un componente panel" a pagina 8-47 e 
"Organizzazione delle azioni per barre e menu" a pagina 8-17. 

Caselle di controllo 



Una casella di controllo e un commutatore che permette all'utente di selezionare uno 
stato attivo/inattivo. Quando la scelta e attiva, la casella di controllo appare con un 
segno di spunta. In caso contrario, la casella di controllo e vuota. Le caselle di 
controllo vengono create utilizzando il componente TCheckBox. 

• Impostare la proprieta Checked a true per far si che la casella appaia selezionata per 
impostazione predefinita. 

• Impostare la proprieta AllowGrayed a true per assegnare alia casella di controllo tre 
possibili stati: selezionato, deselezionato, e grigio. 

• La proprieta State indica se la casella di controllo e selezionata (cbChecked), 
deselezionata (cbUnchecked), oppure grigia (cbGrayed). 

I controlli casella di controllo visualizzano uno dei due possibili stati binari. Lo stato 
indeterminate) viene utilizzato quando altre impostazioni rendono impossibile 
determinare il valore corrente della casella di controllo. 

Pulsanti di opzione 



I pulsanti di opzione presentano una serie di scelte reciprocamente esclusive. E 
possibile creare singoli pulsanti di opzione utilizzando TRadioButton oppure 
utilizzando il componente radio group (TRadioGroup) per organizzare 
automaticamente in gruppi piu pulsanti di opzione. E possibile raggruppare i 
pulsanti di opzione in modo da consentire all'utente di effettuare una scelta da un 
insieme limitato di opzioni. Per maggiori informazioni, consultare la sezione 
"Controlli di raggruppamento" a pagina 9-14. 

Un pulsante di opzione selezionato viene visualizzato come un cerchio con un 
pallino di riempimento. Se non e selezionato, il pulsante di opzione visualizza un 
cerchio vuoto. Per modificare lo stato visuale del pulsante di opzione, assegnare il 
valore true o false alia proprieta Checked. 

Barre strumenti 



Le barre strumenti rappresentano un modo semplice per disporre e gestire i controlli 
visuali. E possibile creare una barra strumenti a partire da un componente panel e da 
pulsanti di scelta rapida, oppure e possibile utilizzare il componente ToolBar e 
aggiungere alia barra strumenti una serie di pulsanti facendo clic destro e scegliendo 
il comando New Button. 
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II componente TToolBar presenta diversi vantaggi: i pulsanti su una barra strumenti 
conservano automaticamente dimensioni e spaziatura uniformi; gli altri controlli 
conservano la propria posizione e altezza relative; i controlli possono essere disposti 
automaticamente su piu righe quando lo spazio orizzontale non e sufficiente; inoltre, 
TToolBar consente di utilizzare varie opzioni di visualizzazione quali la trasparenza, i 
bordi popup oltre a spazi e divisori per raggruppare i controlli. 

Grazie alle liste di azioni o alle bande di azioni e possibile utilizzare un set 
centralizzato di azioni per le barre strumenti e per i menu. Per i dettagli su come 
utilizzare liste di azioni con i pulsanti e le barre strumenti, consultare il paragrafo 
"Uso delle liste di azioni" a pagina 8-25. 

Le barre strumenti possono anche fungere da genitore (contenere) di altri controlli 
come caselle di modifica, caselle combinate, e cosi via. 



Cool bar (solo VCL) 



Una coolbar contiene controlli figlio che possono essere spostati e ridimensionati in 
modo indipendente. Ciascun controllo risiede su un singolo nastro. L'utente 
posiziona i controlli trascinando la maniglia di dimensionamento alia sinistra di 
ciascun nastro. 

II componente coolbar richiede la presenza del file COMCTL32.DLL in versione 4.70 
o successiva (solitamente il file e incluso nella directory Windows \ System o 
Windows \System32) sia durante la progettazione sia in fase di esecuzione. Le 
coolbar non possono essere utilizzate in applicazioni multipiattaforma. 

• La proprieta Bands include una raccolta di oggetti TCoolBand. In fase di 
progettazione, e possibile aggiungere, rimuovere o modificare i nastri con 
l'apposito editor. Per aprire il Bands editor, selezionare la proprieta Bands 
nell' Object Inspector, quindi fare doppio clic sulla colonna Value disposta alia 
destra, oppure fare clic sul pulsante ellissi (...) I nastri possono anche essere creati 
aggiungendo dalla tavolozza nuovi controlli a finestra. 

• La proprieta FixedOrder determina se l'utente puo riordinare i nastri. 

• La proprieta FixedSize determina se i nastri hanno tutti un' altezza uniforme. 



Controlli elenco 



I componenti con elenchi presentano all'utente una serie di elementi fra cui effettuare 
una selezione. Diversi componenti visualizzano elenchi: 



Utilizzare questo com- 
ponente: 

TListBox 
TCheckListBox 
TComboBox 
TTreeView 



Per visualizzare: 

Un elenco di stringhe di testo 

Un elenco con una casella di controllo prima di ciascun elemento 
Una casella di testo a scorrimento con un elenco a discesa 
Un elenco gerarchico 
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Utilizzare questo corn- 
pone nte: 

TListView 



TIconView (CLX only) 

TDateTimePicker 
TMonthCalendar 



Per visualizzare: 

Un elenco di elementi (trascinabili) con possibility di visualizzare icone, 
colonne e intestazioni 

TIconView (solo CLX) 

Un elenco di elementi o dati su righe e colonne, visualizzati come icone 
piccole o grandi 

Una casella di riepilogo per immettere date oppure orari (solo VCL) 
Un calendario per selezionare date (solo VCL) 



Utilizzare i componenti non visuali TStringList e TImageList per gestire serie di 
stringhe e immagini. Per maggiori informazioni sugli elenchi di stringhe, consultare 
"Operazioni con elenchi di stringhe" a pagina 4-16. 



Caselle di riepilogo e caselle di riepilogo con spunta 



Le caselle di riepilogo (TListBox) e le caselle di riepilogo con spunta visualizzano liste 
da cui gli utenti possono slezionare uno o piu elementi. 

• Items utilizza un oggetto TStrings per riempire il controllo con valori. 

• Itemlndex indica qual e l'elemento selezionato nell'elenco. 

• MultiSelect specifica se l'utente pud selezionare piu di un elemento per volta. 

• Sorted determina se l'elenco e ordinato secondo l'ordine alfabetico. 

• Columns specifica il numero di colonne nel controllo elenco. 

• IntegralHeight specifica se la casella di riepilogo mostra solo quegli elementi che 
riempiono completamente lo spazio verticale (solo VCL). 

• ItemHeight specifica l'altezza in pixel di ciascun elemento. La proprieta Style pud 
far si che la proprieta ItemHeight sia ignorata. 

• La proprieta Style determina come un controllo elenco visualizza i propri elementi. 
Per impostazione predefinita, gli elementi sono visualizzati come stringhe. 
Modificando il valore di Style, e possibile creare caselle di riepilogo con 
tracciamento personalizzato in grado di visualizzare gli elementi in modo grafico o 
con altezze differenti. Per informazioni sui controlli con tracciamento 
personalizzato, consultare la sezione "Aggiunta di grafici ai controlli" a 

pagina 6-12. 

Per creare una semplice casella di riepilogo: 

1 All'interno del progetto, trascinare su una scheda un componente casella di 
riepilogo prelevandolo dalla Component palette. 

2 Dimensionare la casella di riepilogo e impostarne l'allineamento. 

3 Fare doppio clic alia destra della proprieta Items o fare clic sul pulsante ellissi per 
visualizzare lo String List Editor. 

4 Utilizzare l'editor per immettere del testo organizzato su piu righe per il 
contenuto della casella di riepilogo. 

5 Scegliere OK. 
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Per consentire agli utenti di selezionare piu elementi nella casella di riepilogo, e 
possibile utilizzare le proprieta ExtendedS elect e MultiSelect. 

Caselle combinate 



Una casella combinata (TComboBox) combina una casella di testo con un elenco a 
scorrimento. Quando l'utente immette dati nel controllo, scrivendo oppure 
selezionando uno dei valori dell'elenco, viene modificato il valore della proprieta 
Text. Se la proprieta AutoComplete e attiva, l'applicazione cerca nella lista e visualizza 
la corrispondenza piu simile al dato via via immesso dall'utente. 

Esistono tre tipi di caselle combinate: standard, a discesa (impostazione predefinita), 
e lista a discesa. 

• Utilizzare la proprieta Style per selezionare il tipo di casella combinata necessaria. 

• Utilizzare csDropDown se si vuole una casella di testo con un elenco a discesa. 
Utilizzare csDropDownList per rendere la casella di testo a sola lettura 
(costringendo cosi l'utente ad effettuare una scelta dall'elenco). Impostare la 
proprieta DropDownCount per modificare il numero di elementi visualizzato 
nell'elenco. 

• Utilizzare csSimple per creare una casella combinata con un elenco fisso che non si 
chiude. Accertarsi di ridimensionare la casella combinata in modo da visualizzare 
gli elementi dell'elenco. 

• Utilizzare csOwnerDrawFixed oppure csOwnerDrawVariable per creare caselle 
combinate con tracciamento personalizzato in grado di visualizzare graficamente gli 
elementi o con altezze differenti. Per informazioni sui controlli con tracciamento 
personalizzato, consultare la sezione "Aggiunta di grafici ai controlli" a 
pagina 6-12. 

In esecuzione, le caselle combinate CLX funzionano in modo diverso rispetto alle 
caselle combinate della VCL. In CLX (ma non nella casella combinata della VCL), e 
possibile aggiungere un elemento a una casella combinata a discesa immettendo del 
testo nel campo di editing e premendo il tasto Invio. E possibile disattivare questa 
funzione impostando InsertMode a ciNone. Alia lista della casella combinata e anche 
possibile aggiungere elementi vuoti (nessuna stringa). Inoltre, se si mantiene 
premuto il tasto freccia, non ci si ferma sull'ultimo elemento dell'elenco della casella 
combinata. Si torna nuovamente all'inizio. 

Viste ad albero 



Un controllo tree view (TTreeView) visualizza gli elementi secondo una struttura con 
rientranze. II controllo dispone di pulsanti che consentono di espandere e contrarre i 
nodi. Assieme alle etichette di testo degli elementi e possibile includere delle icone e 
visualizzare icone differenti per indicare se un nodo e espanso o contratto. E possibile 
anche includere elementi grafici, come, ad esempio, un segno di spunta, che e in 
grado di fornire informazioni sullo stato degli elementi. 

• Indent imposta il numero di pixels che separano in orizzontale gli elementi dai 
rispettivi genitori. 
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• ShowButtons consente la visualizzazione di pulsanti '+' e '-' per indicare se un 
elemento puo essere espanso. 

• ShowLines consente la visualizzazione di linee di connessione per evidenziare le 
relazioni gerarchiche (solo VCL). 

• ShowRoot determina se visualizzare o meno le linee che connettono gli elementi di 
livello superiore (solo VCL). 

Per aggiungere elementi a un controllo vista ad albero in fase di progettazione, fare 
doppio clic sul controllo in modo da visualizzare l'editor Tree View Items. Gli 
elementi aggiunti diventano il valore della proprieta Items. E possibile modificare gli 
elementi in esecuzione utilizzando i metodi della proprieta Items , che e un oggetto di 
tipo TTreeNodes. TTreeNodes ha metodi per aggiungere, cancellare ed esaminare gli 
elementi nella vista albero. 

Le viste ad albero possono visualizzare colonne e sottoelementi in modo analogo ai 
componenti listview in modalita vsReport. 

Viste ad elenco 



I controlli list view, creati utilizzando TListView, visualizzano elenchi in diversi 
formati. Utilizzare la proprieta ViewStyle per scegliere il tipo di elenco desiderato: 

• vslcon e vsSmalllcon visualizzano ciascun elemento come un'icona con un'etichetta. 
L'utente puo trascinare gli elementi all'interno della finestra del controllo vista ad 
elenco (solo VCL). 

• vsList visualizza gli elementi come icone con etichetta che non e possibile 
trascinare. 

• vsReport visualizza gli elementi su righe separate con inf ormazioni disposte in 
colonne. La colonna piu a sinistra contiene una piccola icona e un'etichetta, mentre 
le colonne successive contengono i sottoelementi specif icati dall'applicazione. 
Utilizzare la proprieta ShowColumnHeaders per visualizzare l'intestazione delle 
colonne. 

Selettore data-ora e calendari mensili (solo VCL) 



II componente DateTimePicker visualizza una casella di riepilogo per immettere date 
oppure orari, mentre il componente MonthCalendar presenta un calendario per 
immettere date oppure intervalli di date. Per utilizzare questi componenti e 
necessario avere una versione 4.70 o la versione piu recente del file COMCTL32.DLL 
(di solito presente nella directory Windows \ System oppure Windows \System32) sia 
in fase di progettazione sia durante l'esecuzione. Non sono utilizzabili in 
applicazioni multipiattaforma. 
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Controlli di raggruppamento 



Un'interfaccia grafica e piu facile da utilizzare se controlli e informazioni correlate 
sono presentate in gruppi. C++Builder possiede diversi componenti per raggruppare 
i componenti: 



Utilizzare questo 

componente: Quando si desidera: 

TGroupBox Una casella di gruppo standard con un titolo 

TRadioGroup Un semplice gruppo di pulsanti di opzione 

TPand Un gruppo di controlli piu flessibile 

TScrollBox Una regione a scorrimento contenente controlli 

TTabControl Una serie di separatori di pagine reciprocamente esclusivi 

TPageControl Un insieme di separatori in stile notebook reciprocamente esclusivi, con 
pagine corrispondenti, ognune delle quali puo contenere altri controlli 

THeaderControl Intestazioni di colonna dimensionabili 



Caselle di gruppo e gruppi di pulsanti di opzione 



Una casella di gruppo (TGroupBox) consente di disporre su una scheda piu controlli 
correlati. I controlli raggruppati piu di frequente sono i pulsanti di opzione. Dopo 
avere collocato su una scheda una casella di gruppo, selezionare i componenti dalla 
Component palette e collocarli nella casella di gruppo. La proprieta Caption contiene 
il testo che identifica la casella di gruppo in fase di esecuzione. 

II componente radio group (TRadioGroup) semplifica le operazioni necessarie per 
assemblare piu pulsanti di opzione per farli operare insieme. Per aggiungere pulsanti 
di opzione a un componente radio group, modificare nell'Object Inspector la 
proprieta Items; ciascuna stringa in Items fa si che nella casella di gruppo appaia un 
pulsante di opzione il cui titolo e rappresentato dalla stringa stessa. II valore della 
proprieta Itemlndex determina qual e il pulsante di opzione attualmente selezionato. 
Impostando il valore della proprieta Columns e possibile visualizzare i pulsanti di 
opzione in una sola colonna oppure disposti su piu colonne. Per modificare la 
spaziatura fra i pulsanti, dimensionare il componente radio group. 

Pannelli 



II componente TPanel fornisce un contenitore generico per altri controlli. Di solito i 
pannelli sono utilizzati per raggruppare visivamente piu componenti su una scheda. 
I pannelli possono essere allineati con la scheda in modo da conservare la stessa 
posizione relativa se la scheda fosse dimensionata. La proprieta BorderWidth 
determina l'ampiezza in pixels del bordo attorno a un pannello. 

Su un pannello e possibile anche collocare altri controlli e utilizzare la proprieta Align 
per assicurare il corretto posizionamento sulla scheda di tutti i controlli nel gruppo. E 
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possibile impostare l'allineamento del pannello a alTop in modo che la sua posizione 
rimanga fissa anche se la scheda viene ridimensionata. 

L'aspetto del pannello puo essere modificato facendogli assumere un aspetto rialzato 
o incavato grazie alle proprieta BevelOuter e Bevellnner. E possibile variare i valori di 
queste proprieta per creare differenti effetti 3-D visuali. E bene notare che se si 
desidera solamente uno smusso rialzato o incavato, e possibile utilizzare il controllo 
TBevel che utilizza in minor numero di risorse. 

E possibile anche utilizzare uno o piu pannelli per costruire barre di stato o aree per 
la visualizzazione di informazioni. 

Caselle a scorrimento 



Le caselle a scorrimento (TScrollBox) consentono di creare all'interno di una scheda 
delle aree con funzioni di scorrimento. Spesso le applicazioni devono visualizzare 
piu informazioni di quante ce ne stiano in una determinata area. Alcuni controlli 
come le caselle di riepilogo, i campi memo e le stesse schede, sono in grado di far 
scorrere i propri contenuti. 

Un altro utilizzo delle caselle a scorrimento consiste nel creare piu aree a scorrimento 
(viste) in un'unica finestra.Le viste sono molto comuni nei programmi commerciali 
di elaborazione testi, nei fogli elettronici o nelle applicazioni per la gestione di 
progetti. Le caselle a scorrimento offrono maggior flessibilita in quanto consentono di 
definire in modo arbitrario aree di scorrimento all'interno di una scheda. 

In modo analogo ai pannelli e alle caselle di gruppo, le caselle a scorrimento 
contengono altri controlli, come gli oggetti TButton e TCheckBox. Una casella a 
scorrimento di solito e invisibile. Se i controlli inseriti nella casella a scorrimento non 
sono contenuti completamente nell'area visibile, la casella a scorrimento visualizza 
automaticamente barre di scorrimento. 

Un altro utilizzo di tali caselle e quello di restringere lo scorrimento in determinate 
aree della finestra, come ad esempio in una barra strumenti o in una barra di stato 
(componenti TP ami). Per evitare che si possa far scorrere una barra strumenti o una 
barra di stato, nascondere le barre di scorrimento e posizionare una casella a 
scorrimento nell'area del client della finestra, fra la barra strumenti e la barra di stato. 
Le barre di scorrimento associate alia casella a scorrimento sembreranno appartenere 
alia finestra, ma consentiranno solo di far scorrere l'area all'interno della casella. 

Controlli separatore 



II componente tab (TTabControl) crea una serie di separatori che assomigliano ai 
divisori di un'agenda. E possibile creare separatori modificando nell'Object Inspector 
la proprieta Tab; ciascuna stringa in Tabs rappresenta un separatore. II controllo tab e 
un singolo pannello contenente una serie di componenti. Per modificare l'aspetto del 
controllo si fa clic su di esso, e necessario scrivere un gestore dell'evento OnChange. 
Per creare una finestra di dialogo multipagina, utilizzare un controllo Page. 
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Controlli pagina 



II componente controllo pagina (TPageControl) consiste di un set di pagine adatto alia 
creazione di finestre di dialogo multipagina. Un controllo pagina visualizza piu 
pagine sovrapposte, ognuna delle quali e un oggetto TTabSheet. Nell'interfaccia 
utente, una pagina viene selezionata facendo die sul separatore di pagina nella parte 
superiore del controllo. 

Per creare una nuova pagina in un controllo pagina in fase di progettazione, fare clic 
destro sul controllo e scegliere il comando New page. In esecuzione, e possibile 
aggiungere nuove pagine creando l'oggetto per la pagina e impostandone la 
proprieta PageControl: 

TTabSheet *pTabSheet = new TTabSheet (PageControll) ; 
pTabSheet->PageControl = PageControll; 

Per accedere alia pagina attiva utilizzare la proprieta ActivePage. Per modificare la 
pagina attiva, e possibile impostare le proprieta ActivePage o ActivePagelndex. 

Controlli intestazione 



Un controllo header (THeaderControl) e una serie di intestazioni di colonna che 
l'utente puo selezionare o ridimensionare in fase di esecuzione. Modificare la 
proprieta Sections del controllo per aggiungere o modificare le intestazioni. E 
possibile collocare sezioni di intestazione su colonne o campi. Ad esempio, le sezioni 
di intestazione potrebbero essere collocate sulle caselle di riepilogo (TListBox). 

Controlli di visualizzazione 



Esistono diversi modi per fornire agli utenti le informazioni sullo stato di 
un'applicazione. Ad esempio, alcuni componenti, incluso TForm, hanno una 
proprieta Caption che puo essere impostata durante l'esecuzione. E anche possibile 
creare finestre di dialogo per visualizzare messaggi. Inoltre, i componenti elencati di 
seguito risultano particolarmente utili per fornire in esecuzione un feedback visivo. 



Utilizzare il componente 




o la proprieta: 


Se si vuole: 


TStatusBar 


Visualizzare un'area di stato (di solito nella parte inferiore di una fine- 




stra) 


TProgressBar 


Mostrare lo stato di avanzamento di una determinata operazione 


Hint e ShowHint 


Attivare il fumetto di aiuto o i suggerimenti 


HelpContext e HelpFile 


Collegare la Guida in linea contestuale 


Barre di stato 



Sebbene sia possibile utilizzare un pannello per creare una barra di stato, e piu 
semplice utilizzare il componente TStatusBar. Per impostazione predefinita, la 
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proprieta Align della barra di stato e impostata ad alBottom, che ne determina 
automaticamente posizione e dimensione. 

Se e necessario visualizzare nella barra di stato solo una stringa di testo per volta, 
impostare la proprieta SimplePanel a true e utilizzare la proprieta SimpleText per 
controllare il testo visualizzato nella barra di stato. 

E possibile che una barra di stato venga suddivisa in varie aree di testo, chiamate 
pannelli. Per creare i pannelli, modificare nell'Object Inspector la proprieta Panels 
impostando per ciascun pannello, mediante il Panel editor, le proprieta Width, 
Alignment, e Text. La proprieta Text di ogni pannello contiene il testo visualizzato nel 
pannello. 



Se l'applicazione deve compiere un'operazione molto lunga, e possibile utilizzare 
una barra di avanzamento per mostrare lo stato di avanzamento dell'operazione. 
Una barra di avanzamento visualizza una riga punteggiata che cresce da sinistra a 
destra. 

Figura 9.2 Una barra di avanzamento 



La proprieta Position tiene traccia della lunghezza della linea punteggiata. Le 
proprieta Max e Min determinano l'intervallo di validita di Position. Per fare si che la 
riga cresca, incrementare Position chiamando i metodi StepBy o Steplt. La proprieta 
Step determina l'incremento utilizzato da Steplt. 



Quasi tutti i controlli visuali possono visualizzare in fase di esecuzione sia una Guida 
contestuale sia dei suggerimenti. Le proprieta HelpContext e HelpFile sono usate per 
determinare un numero di contesto per la Guida e il nome del file della Guida del 
controllo. 

La proprieta Hint contiene la stringa di testo che appare quando l'utente sposta il 
puntatore del mouse su un controllo o su un elemento di menu. Per attivare i 
suggerimenti, impostare ShoivHint a true; se si imposta ParentShowHint a true, la 
proprieta ShowHint del controllo assumera lo stesso valore della proprieta del 
genitore. 



Le griglie visualizzano informazioni disposte su righe e colonne. Se si sta scrivendo 
un'applicazione database, utilizzare i componenti TDBGrid o TDBCtrlGrid descritti 
nel Capitolo 19, "Uso dei controlli dati". Oppure, utilizzare una griglia draw 
standard o una griglia stringa. 



Barre di avanzamento 




Proprieta Help e Hint 



Griglie 
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Editor di liste di valori (solo VCL) 

Griglie grafiche 



Una griglia grafica (TDrawGrid) visualizza dati arbitrari in formato tabellare. Per 
riempire le celle della griglia si deve scrivere un gestore per l'evento OnDrawCell. 

• II metodo CellRect restituisce le coordinate video di una cella specificata, mentre il 
metodo MouseToCell restituisce la colonna e la riga della cella situata alle 
coordinate video specificate. La proprieta Selection indica i bordi delle celle 
attualmente selezionate. 

• La proprieta TopRow determina quale riga e attualmente nella parte superiore 
della griglia. La proprieta LeftCol determina la prima colonna visibile sulla sinistra. 
VisibleColCount e VisibleRowCount rappresentano il numero di colonne e righe 
visibili nella griglia. 

• E possibile modificare l'ampiezza o altezza di una colonna o di una riga mediante 
le proprieta ColWidths e RowHeights. Impostare lo spessore delle linee della griglia 
mediante la proprieta GridLineWidth. Aggiungere alia griglia le barre di 
scorrimento mediante la proprieta ScrollBars. 

• Mediante le proprieta FixedCols e FixedRows e possibile decidere se avere colonne o 
righe fisse non soggette a scorrimento. Alle colonne e alle righe fisse e possibile 
assegnare un colore usando la proprieta FixedColor. 

• Le proprieta Options, DefaultColWidth e DefaultRowHeight influenzano anche 
l'aspetto e il comportamento della griglia. 

Griglie per stringhe 



II componente grid string e un discendente di TDrawGrid che aggiunge funzionalita 
specializzate per semplificare la visualizzazione di stringhe. La proprieta Cells elenca 
le stringhe per ciascuna cella della griglia; la proprieta Objects elenca gli oggetti 
associati a ciascuna stringa. Tramite le proprieta Cols e Rows e possibile accedere a 
tutte le stringhe e gli oggetti associati ad una particolare colonna o riga. 

Editor di liste di valori (solo VCL) 



TValueListEditor e una griglia specializzata per editare liste di stringhe contenenti 
coppie nome/valore nel formato Name=Value. I nomi e i valori sono memorizzati 
come discendenti di TStrings che e il valore della proprieta Strings. E possibile cercare 
il valore di un qualsiasi nome utilizzando la proprieta Values. TValueListEditor non e 
utilizzabile per programmi multipiattaforma. 

La griglia contiene due colonne, una per i nomi e una per i valori. Per impostazione 
predefinita, la colonna Name e detta "Key" e la colonna Value e detta "Value". E 
possibile modificare queste impostazioni predefinite impostando la proprieta 
TitleCaptions. E possibile omettere questi titoli utilizzando la proprieta DisplayOptions 
(che controlla anche il dimensionamento quando si ridimensiona il controllo.) 
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Utilizzando la proprieta KeyOptions e possibile controllare se gli utenti possono 
modificare la colonna Name. KeyOptions contiene opzioni separate per consentire 
l'editing, l'aggiunta di nuovi nomi, la cancellazione di nomi e controllare se i nuovi 
nomi devono essere univoci. 

Utilizzando la proprieta ItemProps e possibile controllare le modalita secondo cui gli 
utenti editano le voci nella colonna Value. Ogni elemento ha un oggetto separato 
TItemProp che consente di 

• Fornire una maschera di immissione per controllare la validita dei dati immessi. 

• Specificare la lunghezza massima per i valori. 

• Contrassegnare il valore come a sola lettura. 

• Specificare che l'editor della lista di valori visualizzi una freccia verso il basso per 
aprire una lista di possibili valori tra cui effettuare una scelta oppure un pulsante 
ellissi che inneschi un evento utilizzabile per visualizzare una finestra di dialogo 
in cui immettere i valori. 

Se si specifica che c'e una freccia verso il basso, e necessario fornire la lista di valori 
da cui effettuare la scelta. Questa lista puo essere una lista statica (la proprieta 
PickList dell'oggetto TItemProp ) oppure e possibile aggiungere dinamicamente i 
valori in fase di esecuzione utilizzando l'evento OnGetPickList dell'editor della 
lista di valori. E possibile anche combinare queste modalita e avere una lista statica 
modificabile con il gestore di evento OnGetPickList. 

Se si specifica che c'e un pulsante ellissi, e necessario fornire la risposta che si 
verifica quando l'utente fa clic su quel pulsante (inclusa l'impostazione di un 
valore, se e il caso). Si fornisce questa risposta scrivendo un gestore di evento 
OnEditButton Click. 

Controlli grafici 



I componenti seguenti semplificano l'incorporazione di elementi grafici in 
un'applicazione. 

Utilizzare questo com- 



ponente: Per visualizzare: 

Tlmage File grafici 

TShape Forme geometriche 

TBevel Linee 3D e frame 

TPaintBox Grafici disegnati dal proprio programma in fase di esecuzione 

T Animate File AVI (solo VCL) 



Si noti che questi includono le comuni routine di disegno (Repaint, Invalidate e cosi 
via) che non avranno mai bisogno di ricevere il fuoco. 
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Immagini 



II componente image (immagine) visualizza un'immagine grafica, come una bitmap, 
un'icona o un metafile. La proprieta Picture determina l'immagine grafica da 
visualizzare. Utilizzare Center, AutoSize, Stretch e Transparent per impostare le 
opzioni di visualizzazione. Per maggiori informazioni consultare "Panoramica sulla 
programmazione dei grafici" a pagina 10-1. 

Forme 



II componente shape (forma) visualizza una forma geometrica.E un controllo che e 
basato su finestra (non basato su widget in CLX) e pertanto non puo ricevere l'input 
dell'utente. La proprieta Shape determina la forma assunta dal controllo. Per 
modificare il colore della forma o aggiungere un motivo di riempimento, utilizzare la 
proprieta Brush che contiene un oggetto TBrush. II modo in cui la forma viene 
tracciata dipende dalle proprieta Color e Style di TBrush. 

Linee smussate 



II componente bevel (TBevel) e una linea che puo apparire incavata oppure a sbalzo. 
Alcuni componenti, come TPanel, hanno proprieta intrinseche per creare bordi 
smussati. Quando tali proprieta non sono disponibili, l'uso di TBevel consente di 
creare contorni smussati, riquadri o cornici. 

Caselle di disegno 



II componente paint box (TPaintBox) consente all'applicazione di tracciare un disegno 
su una scheda. Per riprodurre direttamente un'immagine sul Canvas della casella di 
disegno occorre scrivere un gestore per l'evento OnPaint. Non e consentito disegnare 
al di fuori dei bordi della casella di disegno. Per maggiori informazioni consultare 
"Panoramica sulla programmazione dei grafici" a pagina 10-1. 

Controlli Animation (solo VCL) 



II componente animation (animazione) e una finestra che visualizza senza sonoro un 
file Audio Video Interleaved (AVI). Un file AVI e composto da una serie di frame in 
formato bitmap, simile ad un film. Sebbene i file AVI possano contenere una traccia 
sonora, i controlli animazione funzionano soltanto con filmati AVI senza suono. I file 
utilizzati possono essere sia in formato AVI non compresso sia in formato AVI 
compresso mediante la codifica RLE (run-lenght encoding). II controllo di 
animazione non puo essere utilizzato in programmi multipiattaforma. 

Di seguito sono elencate alcune importanti proprieta di un controllo animation: 

• ResHandle e l'handle di Windows per il modulo che contiene il filmati AVI sotto 
forma di risorsa. Impostare in fase di esecuzione ResHandle alio handle dell'istanza 
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oppure alio handle di modulo di quel modulo che include la risorsa di 
animazione. Dopo aver impostato ResHandle, impostare la proprieta ResID o 
ResName per specificare quale risorsa nel modulo indicato e il filmato AVI che 
dovrebbe essere visualizzato dal controllo animazione. 

Impostare AutoSize a true per fare in modo che il controllo animazione regoli le 
proprie dimensioni alle dimensione dei fotogrammi nel filmato AVI. 
StartFrame e StopFrame specificano a quali fotogrammi iniziare e fermare il filmato. 
Impostare CommonAVI per visualizzare uno dei filmati AVI di Windows forniti 
con Shell32.DLL. 

Specificare quando iniziare e interrompere l'animazione impostando, 
rispettivamente, la proprieta Active a true o false, e quante ripetizioni eseguire 
impostando la proprieta Repetitions. 

La proprieta Timers permette di visualizzare i frame utilizzando un timer. Questo 
e utile per sincronizzare la sequenza di animazioni con altre azioni, come ad 
esempio l'esecuzione di una traccia audio. 



Tipi di controlli 9-21 



Controlli grafici 



9-22 Guida alia programmazione 



Capitolo 




Operazioni con elementi grafici e 

multimediali 

L'uso di elementi grafici e multimediali puo aggiungere un tocco di raffinatezza alle 
proprie applicazioni. C++Builder offre vari modi per introdurre queste funzionalita 
nelle applicazioni. Per aggiungere elementi grafici, e possibile inserire immagini 
disegnate in precedenza in fase di progettazione, e possibile crearle usando un 
controllo grafico in fase di esecuzione oppure tracciarle mediante un controllo grafico 
in fase di esecuzione. Per aggiungere funzionalita multimediali, C++Builder include 
uno speciale componente in grado di riprodurre file audio e video. 

I componenti multimediali sono disponibili solo nella VCL. 



Panoramica sulla programmazione dei grafici 



I componenti grafici della VCL, definiti nella unit Graphics, incapsulano la Graphics 
Device Interface (GDI) di Windows, semplificando notevolmente l'aggiunta di grafici 
alle applicazioni Windows. I componenti grafici CLX definiti nella unit QGraphics 
incapsulano i widget grafici Qt per l'aggiunta della grafica alle applicazioni 
multip iattaf or ma . 

Per disegnare grafici in un'applicazione C++Builder, si deve disegnare sul canvas di 
un oggetto, anziche direttamente sull'oggetto stesso. II canvas e una proprieta 
deU'oggetto, ed e essa stessa un oggetto. II principale vantaggio dell'oggetto Canvas 
e che gestisce efficacemente le risorse e si occupa del contesto del dispositivo, 
cosicche i programmi possono usare gli stessi metodi, indipendentemente dal fatto 
che si disegni sullo schermo, su una stampante, sui bitmap o sui metafiles (disegno in 
CLX). I Canvas sono disponibili solo in fase di esecuzione, pertanto tutte le 
operazioni sui canvas devono essere gestite mediante del codice apposito. 
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Poiche TCanvas e un gestore di risorse wrapper nel contesto dei dispositivi di 
Windows, nel canvas si possono usare anche tutte le funzioni GDI di Windows. La 
proprieta Handle del canvas e lo Handle di contesto del dispositivo. 

TCanvas e un gestore di risorse wrapper attorno a un painter di Qt. La proprieta 
Handle del canvas eun puntatore con tipo a un'istanza dell'oggetto painter di QT. II 
fatto che il puntatore all'istanza sia esposto permette di utilizzare funzioni grafiche 
della libreria Qt a basso livello che richiedono QPainterH. 

La modalita di visualizzazione delle immagini grafiche nelle applicazioni dipende 
dal tipo di oggetto sul cui canvas si sta disegnando. Se si sta disegnando direttamente 
sul canvas di un controllo, rimmagine viene visualizzata immediatamente. Tuttavia, 
se si sta disegnando su un'immagine fuori schermo, come ad esempio un canvas di 
un oggetto TBitmap, l'immagine non viene visualizzata finche un controllo non la 
copia dalla bitmap sul canvas di un altro controllo. Cio significa che, quando si 
disegnano delle bitmap e le si assegna a un controllo image, l'immagine appare solo 
quando il controllo ha l'opportunita di elaborarne il messaggio (VCL) o l'evento 
(CLX) OnPaint). 

Durante le operazioni con elementi grafici, spesso si incontrano termini quali 

tracciamento e disegno: 

• II tracciamento e la creazione di un singolo e determinato elemento grafico, come 
una linea o una figura, mediante del codice. Nel codice, si impartisce a un oggetto 
il comando di tracciare un determinato elemento grafico in una certa posizione del 
suo canvas mediante una chiamata al metodo di tracciamento del canvas. 

• II disegno e la creazione dell'aspetto globale di un oggetto. II disegno di solito 
comporta il tracciamento. Cio significa che, in risposta agli eventi OnPaint, un 
oggetto di solito traccia alcuni elementi grafici. Una casella di testo, ad esempio, 
disegna se stessa tracciando dapprima un rettangolo e successivamente del testo al 
suo interno. Un controllo shape, d'altro canto, disegna se stesso tracciando un 
singolo elemento grafico. 

L'esempio all'inizio del capitolo illustra come tracciare vari elementi grafici, ma 
questi lo fanno in risposta ad eventi OnPaint. Le sezioni successive mostrano come 
compiere le stesse operazioni di tracciamento in risposta ad altri eventi. 

Aggiornamento dello schermo 



Talvolta il sistema operativo determina che gli oggetti sullo schermo hanno bisogno 
di rinnovare il loro aspetto, e quindi genera in Windows dei messaggi WM_PAINT, 
che la VCL inoltra agli eventi OnPaint . (Se si utilizza CLX per lo sviluppo 
multipiattaforma, viene generato un evento Paint, che CLX indirizza a eventi 
OnPaint). Se si e scritto un gestore di evento OnPaint per quell'oggetto, esso verra 
chiamato quando si usera il metodo Refresh. II nome predefinito generato per il 
gestore di evento OnPaint in una scheda e FormPaint. A volte, puo essere necessario 
usare il metodo Refresh per effettuare l'aggiornamento di un componente o di una 
scheda. Per esempio, si potrebbe chiamare Refresh nel gestore di evento OnResize 
della scheda per visualizzare di nuovo tutti gli elementi grafici oppure, nel caso si usi 
la VCL, per dipingere lo sfondo di una scheda. 



10-2 Guida alia programmazione 



Panoramica sulla p r o g r a m m az i o n e dei grafici 



Mentre alcuni sistemi operativi gestiscono automaticamente il ridisegno dell'area 
client di una finestra che e stata invalidata, Windows non lo fa. Nel sistema operativo 
Windows tutto cio che viene disegnato sullo schermo e permanente. Quando una 
scheda o un controllo viene oscurato temporaneamente, per esempio durante il 
disegno di una finestra, la scheda o il controllo devono dipingere di nuovo l'area 
oscurata quando vengono riesposti. Per ulteriori informazioni sul messaggio 
WM_PAINT, consultare la Guida in linea di Windows. 

Se si usa il controllo TImage per visualizzare sulla scheda un'immagine grafica, le 
operazioni relative alia pittura e aH'aggiomamento del grafico contenuto in TImage 
vengono gestite automaticamente. La proprieta Picture specifica la bitmap attuale, il 
disegno o un altro oggetto grafico visualizzato da TImage. E possibile anche 
impostare la proprieta Proportional per garantire che l'immagine possa essere 
visualizzata completamente nel controllo immagine senza alcuna distorsione. 
Disegnando su un controllo TImage, si crea un'immagine persistente. 
Conseguentemente, non occorre fare nulla per ridisegnare l'immagine contenuta. Al 
contrario, il canvas di TPaintBox mappa direttamente sul dispositivo di schermo 
(VCL) o sul painter (CLX), e pertanto qualsiasi cosa disegnata sul canvas di PaintBox 
e transitoria. Cio e vero per quasi tutti i controlli, compresa la scheda stessa. Percio, se 
si disegna o si dipinge su un TPaintBox nel suo costruttore, occorrera aggiungere quel 
codice al gestore dell'evento OnPaint affinche l'immagine venga ridipinta ogni volta 
che l'area client viene invalidata. 



Tipi di oggetti grafici 



Le librerie VCL/ CLX forniscono gli oggetti grafici elencati nella Tabella 10.1. Questi 
oggetti hanno metodi per disegnare sul canvas, come descritto nel paragrafo "Uso 
dei metodi Canvas per disegnare oggetti grafici" a pagina 10-10 e per caricare e 
salvare file grafici, come descritto nel paragrafo "Caricamento e salvataggio dei file 
grafici" a pagina 10-20. 

Tabella 10.1 Tipi di oggetti grafici 



Oggetto 

Picture 



Bitmap 



Clipboard 



Descrizione 

Serve per contenere un'immagine grafica. Per aggiungere altri formati di 
file grafici, si deve usare il metodo Register di Picture. Questo metodo 
consente di gestire file arbitrari come la visualizzazione delle immagini 
nel relativo controllo. 

Un potente oggetto grafico usato per creare, manipolare (ridurre in scala, 
far scorrere, ruotare e dipingere) e memorizzare immagini su disco. La 
creazione di copie di una bitmap e molto rapida, poiche viene copiato 
Vhandle, non l'immagine. 

Rappresenta il contenitore per qualsiasi testo o grafico da tagliare, 
copiare o incollare da o in un'applicazione. Con la clipboard e possibile 
ottenere e recuperare dati secondo il formato appropriato; gestire il 
conteggio dei riferimenti, e l'apertura e la chiusura dela clipboard; 
gestire e manipolare i formati per gli oggetti nella clipboard. 
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Tabella 10.1 Tipi di oggetti grafici (continua) 



Oggetto 

Icon 

Metafile (VCL only) 
Drawing (CLX only) 



Descrizione 

Rappresenta il valore caricato da un file icona di Windows (file ::ICO). 

Contiene un file, che registra le operazioni necessarie per costruire 
un'immagine, anziche contenere gli effettivi pixel della bitmap 
deH'immagine. I metafile o i disegni sono estremamente scalabili senza 
perdita dei dettagli dell'immagine e spesso richiedono molta meno 
memoria delle bitmap, in modo particolare per i dispositivi ad alta 
risoluzione, come le stampanti. Comunque, i metafile e i disegni non 
vengono visualizzati velocemente quanto le bitmap. Usare un metafile o 
un disegno quando la versatilita o la precisione sono piu importanti 
delle prestazioni. 



Proprieta e metodi comuni dell'oggetto Canvas 



La Tabella 10.2 elenca le proprieta dell'oggetto Canvas usate piu di frequente. Per un 
elenco completo delle proprieta e dei metodi, consultare il componente TCanvas nella 
Guida in linea. 



Tabella 10.2 Proprieta comuni dell'oggetto Canvas 



Proprieta 

Font 
Brush 

Pen 

PenPos 
Pixels 



Descrizione 

Specifica il font da usare quando si scrive del testo nell'immagine. Per 
specificare il font, il colore, le dimensioni e lo stile del font, si devono 
impostare le proprieta dell'oggetto TFont. 

Determina il colore e il modello che il canvas usa per riempire i grafici e 
gli sfondi. Per specificare il colore e il modello o la bitmap da usare 
quando si riempiono gli spazi sul canvas, si devono impostare le 
proprieta dell'oggetto TBrush. 

Specifica il tipo di penna che il canvas usa per tracciare le linee e 
disegnare le figure. Per specificare il colore, lo stile, la larghezza e il 
modo della penna, si devono impostare le proprieta dell'oggetto TPen. 

Specifica la posizione di disegno attiva della penna. 

Specifica il colore dell'area di pixel all'interno del ClipRect attivo. 



Queste proprieta sono descritte in modo piu approfondito nella sezione "Uso delle 
proprieta dell'oggetto Canvas" a pagina 10-5. 

La Tabella 10.3 riporta un elenco dei vari metodi che e possibile usare: 

Tabella 10.3 Metodi comuni dell'oggetto Canvas 
Metodo 

Arc 



Chord 

CopyRect 
Draw 



Descrizione 

Disegna un arco suH'immagine lungo il perimetro deU'ellisse delimitata 
dal rettangolo specificato. 

Disegna una figura chiusa rappresentata dall'intersezione di una linea e 
di un'ellisse. 

Copia parte di un'immagine da un altro canvas nel canvas. 

Rappresenta l'oggetto grafico specificato dal parametro Graphic sul 
canvas nella posizione indicata dalle coordinate (X, Y). 
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Tabella 10.3 Metodi comuni dell'oggetto Canvas (continua) 



Descrizione 

Disegna l'ellisse definita da un rettangolo di delimitazione sul canvas. 

Riempie il rettangolo specificato sul canvas usando il pennello attivo. 

Riempie un'area del canvas usando il pennello attivo. 

Disegna un rettangolo usando il pennello del canvas per disegnare il 
bordo. 

Disegna una linea sul canvas dalla posizione della PenPos al punto 
specificato da X e Y, e imposta la posizione della penna a (X, Y). 

Cambia la posizione di disegno attiva al punto (X,Y). 

Disegna a forma di torta la sezione dell'ellisse delimitata dal rettangolo 
(XI, Yl) e (X2, Y2) sul canvas. 

Disegna una serie di linee sul canvas collegando i punti per cui passa e 
chiudendo la figura con una linea dall'ultimo punto al primo. 

Disegna una serie di linee sul canvas con la penna attiva, collegando 
ciascuno dei punti passati in Points. 

Traccia sul canvas un rettangolo il cui angolo superiore sinistra e 
posizionato nel punto (XI, Yl) e il cui angolo inferiore destro e 
posizionato nel punto (X2, Y2). Utilizzare il metodo Rectangle per 
tracciare un riquadro con Pen e riempilo con Brush. 

Disegna a rettangolo con gli angoli arrotondati sul canvas. 

Disegna un grafico sul canvas in modo che rimmagine trovi posto nel 
rettangolo specificato. II grafico puo aver bisogno di cambiare le 
dimensioni o l'aspetto per stare nel rettangolo. 

Restituisce, rispettivamente, l'altezza e la larghezza di una stringa nel 
font corrente. L'altezza include lo spazio tra le righe. 

Scrive una stringa sul canvas, partendo dal punto (X,Y), e quindi 
aggiorna la posizione della penna PenPos alia fine della stringa. 

Scrive una stringa dentro una regione; qualsiasi parte della stringa che 
cade al di fuori della regione non viene visualizzata. 

Questi metodi sono descritti in modo piu approfondito nel paragrafo "Uso dei 
metodi Canvas per disegnare oggetti grafici" a pagina 10-10. 



Metodo 

Ellipse 
FillRect 

FloodFill (VCL only) 
FrameRect 

LineTo 

MoveTo 
Pie 

Polygon 
Polyline 
Rectangle 



RoundRect 
StretchDraw 



TextHeight, 
TextWidth 

TextOut 



TextRect 



Uso delle proprieta dell'oggetto Canvas 



Con l'oggetto Canvas e possibile impostare le proprieta di una penna per disegnare 
linee, di un pennello per riempire le figure, di un font per scrivere il testo e di un 
array di pixel per rappresenta l'immagine. 

In questa sezione vengono trattati i seguenti argomenti: 

• Uso delle penne. 

• Uso dei pennelli. 

• Lettura e impostazione dei pixel. 
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Uso delle penne 

La proprieta Pen di un canvas controlla il modo in cui appaiono le linee, comprese 
quelle disegnate come contorno delle figure. Disegnare una retta significa in realta 
cambiare un gruppo di pixel che si trovano tra due punti. 

La penna stessa ha quattro proprieta che possono essere modificate: Color, Width, 
Style e Mode. 

• La proprieta Color modifica il colore della penna. 

• La proprieta Width modifica la larghezza della penna. 

• La proprieta Style modifica lo stile della penna. 

• La proprieta Mode cambia il modo della penna. 

I valori di queste proprieta determinano come la penna cambia i pixel della linea. Per 
impostazione predefinita, ogni penna comincia con il colore nero, la larghezza di 1 
pixel, lo stile continuo e il modo chiamato copy che sovrascrive tutto cio che si trova 
gia sul canvas. 

E possibile utilizzare TPenRecall per salvare e ripristinare rapidamente le proprieta 
delle penne. 

Modifica del colore della penna 

E possibile impostare il color di una penna come si fa con qualsiasi altra proprieta 
Color in fase di esecuzione. II colore di una penna determina il colore delle linee che la 
penna disegna, comprese quelle disegnate come contorni delle figure, oltre che le 
altre linee e le spezzate. Per cambiare il colore della penna, si deve assegnare un 
valore alia proprieta Color della penna. 

Per consentire all'utente di scegliere un nuovo colore per la penna, occorre mettere 
una griglia di colori nella barra strumenti della penna. Questa griglia puo impostare i 
colori del primo piano e dello sfondo. Per uno stile di penna non griglia, occorre 
considerare il colore dello sfondo, che viene disegnato negli spazi tra i segmenti. II 
colore dello sfondo viene impostato nella proprieta Color del pennello. 

Poiche l'utente sceglie un nuovo colore facendo clic sulla griglia, il codice seguente 
cambia il colore della penna in risposta all'evento OnClick: 

void __fastcall TForml: : PenColorClick (TObject *Sender) 

{ 

Canvas->Pen->Color = PenColor->ForegroundColor; 

} 

Modifica della larghezza della penna 

La larghezza di una penna determina lo spessore, in pixel, delle linee che vengono 
disegnate. 

Se lo spessore e maggiore di 1, Windows disegna sempre linee continue, 
indipendentemente dal valore della proprieta Style della penna. 

Per modificare la larghezza della penna, si deve assegnare un valore numerico alia 
proprieta Width della penna. 
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Si supponga di avere una barra di scorrimento sulla barra strumenti della penna per 
impostare i valori dello spessore della penna. Si supponga inoltre di voler aggiornare 
l'etichetta accanto alia barra di scorrimento per fornire informazioni di controllo 
all'utente. Usando la posizione della barra di scorrimento per determinare la 
larghezza della penna, questa viene aggiornata ogni volta che la posizione cambia. 

II codice che segue indica come gestire l'evento OnChange della barra di scorrimento: 

void fastcall TForml: :PenWidthChange(TObject *Sender) 

{ 

Canvas->Pen->Width = PenWidth->Position; // set the pen width directly 

PenSize->Caption = IntToStr (PenWidth->Position) ; // convert to string 

} 

Modifica dello stile della penna 

La proprieta Style della penna consente di impostare linee continue, linee 
tratteggiate, linee punteggiate, e cosi via. 

Se si sta sviluppando un'applicazione multipiattaforma da distribuire in ambiente 
Windows, Windows non supporta gli stili tratteggiato e punteggiato per penne piu 
spesse di un pixel e disegna come continue le penne piu spesse, indipendentemente 
dallo stile specificato. 

L'impostazione delle proprieta di una penna e ideale per avere controlli differenti 
che condividono lo stesso gestore per gestire gli eventi. Per determinare quale 
controllo ha di fatto ricevuto l'evento, si deve contrassegnare il parametro Sender. 

Per creare un gestore per gli eventi OnClick relativi ad un gruppo di sei pulsanti di 
stile su una barra strumenti della penna, occorre: 

1 Selezionare tutti e sei i pulsanti e quindi Object Inspector I Events I OnClick e nella 
colonna Handler scrivere SetPenStyle. 

C++Builder genera un gestore di evento vuoto di nome SetPenStyle e lo collega agli 
eventi OnClick di tutti e sei pulsanti. 

2 Riempire il gestore di evento generato impostando lo stile della penna in funzione 
del valore di Sender, ossia del controllo che ha inviato l'evento OnClick: 

void __fastcall TForml: : SetPenStyle (TObject *Sender) 

{ 

if (Sender == SolidPen) 

Canvas->Pen->Style = psSolid; 
else if (Sender == DashPen) 

Canvas->Pen->Style = psDash; 
else if (Sender == DotPen) 

Canvas->Pen->Style = psDot; 
else if (Sender == DashDotPen) 

Canvas->Pen->Style = psDashDot; 
else if (Sender == DashDotDotPen) 

Canvas->Pen->Style = psDashDotDot; 
' else if (Sender == ClearPen) 

Canvas->Pen->Style = psClear; 

} 
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II gestore di evento visto in precedenza potebbe essere ulteriormente ridotto 
ponendo le costanti relative alio stile della penna nelle proprieta Tag dei pulsanti 
relativi alio stile delle penne. In questo caso, il codice dell'evento sarebbe simile al 
seguente:: 

void __fastcall TForml: :SetPenStyle (TObject *Sender) 
{ 

if (Sender->lnheritsFrom (__classid (TSpeedButton) ) 
Canvas->Pen->Style = (TPenStyle) ( (TSpeedButton *) Sender) ->Tag; 

} 

Modifica del modo della penna 

La proprieta Mode della penna permette di specificare i vari modi per combinare il 
colore della penna con il colore sul canvas. Per esempio, la penna puo essere sempre 
nera, essere l'inverso del colore dello sfondo del canvas, l'inverso del colore della 
penna, e cosi via. Per informazioni dettagliate, consultare TPen nella Guida in linea. 

Rilevazione della posizione della penna 

La posizione corrente di disegno, cioe la posizione dalla quale la penna inizia a 
disegnare la successiva linea, e chiamata posizione della penna. II canvas memorizza 
questa posizione nella proprieta PenPos.La posizione della penna influenza solo il 
disegno delle linee; per le figure e per il testo, occorre specificare le coordinate 
necessarie. 

Per impostare la posizione della penna, si deve chiamare il metodo MoveTo del 
canvas. Per esempio, il codice seguente sposta la posizione della penna nell'angolo 
superiore sinistra del canvas: 

Canvas ->MoveTo (0, 0); 

Disegnando una linea con il metodo LineTo, si sposta anche la posizione attuale al 
punto finale della linea. 

Uso dei pennelli 

La proprieta Brush di un canvas controlla il modo in cui le aree vengono riempite, 
compreso l'interno delle figure. Riempire un'area con un pennello equivale a 
cambiare una grande quantita di pixel adiacenti in un modo specificate 

II pennello ha tre proprieta che e possibile manipolare: 

• Proprieta Color, modifica il colore di riempimento. 

• La proprieta Style modifica lo stile del pennello. 

• La proprieta Bitmap usa una bitmap come modello di pennello. 

I valori di queste proprieta determinano il modo in cui il canvas riempie le figure o le 
altre aree. Per impostazione predefinita, ogni pennello comincia con il colore bianco, 
con uno stile continuo e con nessuna bitmap come modello. 

E possibile utilizzare TBrushRecall per salvare e ripristinare rapidamente le proprieta 
dei pennelli. 
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Modifica del colore del pennello 

II colore di un pennello determina quale colore usa il canvas per riempire le figure. 
Per cambiare il colore di riempimento, occorre assegnare un valore alia proprieta 
Color del pennello. II pennello viene usato per il colore dello sfondo nel testo e del 
disegno della linea, cosicche, normalmente, basta impostare la proprieta Color dello 
sfondo. 

E possibile impostare il colore del pennello proprio come si fa con il colore della 
penna, in risposta ad un clic su una griglia di colori sulla barra strumenti del pennello 
(consultare "Modifica del colore della penna" a pagina 10-6): 

void __fastcall TForml: :BrushColorClick(TObject *Sender) 
{ 

Canvas->Brush->Color = BrushColor->BackgroundColor; 

} 

Modifica dello stile del pennello 

Lo stile di un pennello determina quale modello usa il canvas per riempire le figure. 
E possibile specificare diversi modi per combinare il colore del pennello con tutti i 
colori gia presenti sul canvas. Gli stili predefiniti comprendono il colore uniforme, 
nessun colore e vari modelli di linea e di tratteggio. 

Per cambiare lo stile di un pennello, occorre impostare la sua proprieta Style ad uno 
dei valori predefiniti: bsSolid, bsClear, bsHorizontal, bsVertical, bsFDiagonal, 
bsBDiagonal, bsCross o bsDiagCross. 

Questo esempio imposta gli stili del pennello condividendo un gestore per gli eventi 
OnClick relativi ad un gruppo di otto pulsanti per gli stili di pennello. Tutti e otto i 
pulsanti vengono selezionati, viene impostato Object Inspector I Events I OnClick, e il 
gestore OnClick viene chiamato SetBrushStyle. II codice del gestore e: 

void __fastcall TForml: : SetBrushStyle (TObject *Sender) 
{ 



if (Sender == SolidBrush) 


Canvas - 


->Brush- 


>Style = bsSolid; 


else if 


( Sender 


== ClearBrush) 


Canvas - 


->Brush- 


■>Style = bsClear; 


else if 


( Sender 


== HorizontalBrush) 


Canvas - 


->Brush- 


■>Style = bsHorizontal; 


else if 


( Sender 


== VerticalBrush) 


Canvas - 


->Brush- 


■>Style = bsVertical; 


else if 


( Sender 


== FDiagonalBrush) 


Canvas - 


->Brush- 


>Style = bsFDiagonal; 


else if 


( Sender 


== BDiagonalBrush) 


Canvas - 


->Brush- 


■>Style = bsBDiagonal; 


else if 


( Sender 


== CrossBrush) 


Canvas - 


->Brush- 


■>Style = bsCross; 


else if 


( Sender 


== DiagCrossBrush) 


Canvas - 


->Brush- 


->Style = bsDiagCross; 



} 

II gestore di evento visto in precedenza potebbe essere ulteriormente ridotto 
ponendo le costanti relative alio stile del pennello nelle proprieta Tag dei pulsanti 
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relativi alio stile del pennello. In questo caso, il codice dell'evento sarebbe simile al 
seguente: 

void __fastcall TForml: :SetBrushStyle (TObject *Sender) 
{ 

if (Sender->InheritsFrom ( classid (TSpeedButton) ) 

Canvas->Brush->Style = (TBrushStyle) ((TSpeedButton *) Sender) ->Tag; 

} 

Impostazione del la proprieta Bitmap del pennello 

La proprieta Bitmap di un pennello permette di specificare un'immagine bitmap da 
usare come modello per riempire le figure e le altre aree. 

L'esempio seguente carica una bitmap da un file e la assegna al pennello del canvas 
di Forml: 

BrushBmp->LoadFromFile ( "MyBitmap .bmp" ) ; 
Forml->Canvas->Brush->Bitroap = BrushBmp; 
Forml->Canvas->FillRect (Rect (0,0,100,100) ) ; 

II pennello non si impossessa dell'oggetto Bitmap assegnato alia sua proprieta Bitmap. 
Bisogna assicurarsi che l'oggetto Bitmap rimanga valido per tutta la durata del 
pennello, e che successivamente venga liberato. 

Lettura e impostazione dei pixel 

Si notera che ogni canvas ha una proprieta indicizzata Pixels che rappresenta i singoli 
punti colorati che costituiscono l'immagine sul canvas. Raramente e necessario 
accedere direttamente a Pixels, essa e disponibile solo per eseguire facilmente piccole 
azioni, come le ricerca o l'impostazione del colore di un pixel. 

L'impostazione e la rilevazione dei singoli pixel sono migliaia di volte piu lente 
dell'esecuzione di operazioni grafiche sulle regioni. Non usare la proprieta Pixel 
dell'array per accedere ai pixel dell'immagine di un generico array. Per l'accesso ad 
elevate prestazioni ai pixel dell'immagine, consultare la proprieta TBitmap-.ScanLine. 

Uso dei metodi Canvas per disegnare oggetti grafici 



Questa sezione mostra come usare alcuni metodi comuni per disegnare oggetti 
grafici. Gli argomenti trattati sono: 

• Disegno di linee e spezzate. 

• Disegno di figure. 

• Disegno di rettangoli arrotondati. 

• Disegno di poligoni. 

Disegno di linee e spezzate 

Un canvas puo disegnare linee rette e spezzate. Una linea retta e solo una riga di 
pixel compresi tra due punti. Una spezzata e una serie di linee rette, collegate alle 
estremita. II canvas disegna tutte le linee usando la sua penna. 
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Disegno di linee 

Per disegnare una linea retta su un canvas, si deve usare il metodo LineTo del canvas. 

LineTo disegna una linea dalla posizione attuale della penna al punto specificato e 
rende il punto finale della linea la posizione attiva. II canvas disegna la linea usando 
la sua penna. 

Per esempio, il metodo seguente disegna diagonalmente linee incrociate in una 
scheda ogni volta che la scheda viene dipinta: 

void fastcall TForml: :FormPaint (TObject *Sender) 

{ 

Canvas->MoveTo(0,0) ; 

Canvas->LineTo (ClientWidth, ClientHeight) ; 
Canvas->MoveTo(0, ClientHeight) ; 
Canvas->LineTo (ClientWidth, 0); 

} 

Disegno di spezzate 

Oltre alle singole linee, il canvas puo disegnare anche spezzate, cioe gruppi di un 
numero qualunque di segmenti consecutivi. 

Per disegnare una spezzata su un canvas, si deve chiamare il metodo Polyline del 
canvas. 

II parametro passato al metodo Polyline e un array di punti.Si puo pensare ad una a 
spezzata come all'esecuzione di un MoveTo sul primo punto e di un LineTo su ciascun 
punto successive Per disegnare piu linee, Polyline e piu rapido dell'uso dei metodi 
MoveTo e LineTo, in quanto viene eliminato l'overhead derivante dalle successive 
chiamate. 

II metodo seguente, per esempio, disegna un rombo in una scheda: 

void __fastcall TForml: :FormPaint (TObject *Sender) 

{ 

TPoint vertices [5] ; 
vertices [0] = Point (0, 0) ; 
vertices [1] = Point (50, 0) ; 
vertices [2] = Point (75, 50); 
vertices [3] = Point (25, 50); 
vertices [4] = Point (0, 0) ; 
Canvas->Polyline (vertices, 4); 

} 

Si noti che l'ultimo parametro di Polyline e l'indice dell'ultimo punto, e non il numero 
di punti. 

Disegno di figure 

I canvas hanno metodi per disegnare tipi differenti di figure. II canvas disegna il 
contorno di una figura con la sua penna, quindi ne riempie l'interno con il suo 
pennello. La linea che rappresenta il bordo della figura e controllata dall'oggetto Pen 
attivo. 

In questa sezione vengono trattati i seguenti argomenti: 
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• Disegno di rettangoli ed ellissi. 

• Disegno di rettangoli arrotondati. 

• Disegno di poligoni. 

Disegno di rettangoli ed ellissi 

Per disegnare un rettangolo o un'ellisse su un canvas, si deve chiamare il metodo 
Rectangle o il metodo Ellipse del canvas, passando le coordinate di un rettangolo di 
contorno. 

II metodo Rectangle disegna il rettangolo di contorno; Ellipse disegna un'ellisse che 
tocca tutti i lati del rettangolo. 

II metodo seguente disegna un rettangolo riempiendo il quadrante superiore sinistra 
di una scheda, quindi disegna un'ellisse nella stessa area: 

void __fastcall TForml: :FormPaint (TObject *Sender) 
{ 

Canvas->Rectangle(0, 0, ClientWidth/2 , ClientHeight/2 ) ; 
Canvas->Ellipse(0, 0, ClientWidth/2, ClientHeight/2); 

} 

Disegno di rettangoli arrotondati 

Per disegnare un rettangolo arrotondato su un canvas, si deve chiamare il metodo 
RoundRect del canvas. 

I primi quattro parametri passati a RoundRect sono un rettangolo di contorno, 
proprio come awiene per il metodo Rectangle o per il metodo Ellipse. RoundRect 
accetta altri due parametri che indicano come disegnare gli angoli arrotondati. 

II metodo seguente, per esempio, disegna un rettangolo arrotondato nel quadrante 
superiore sinistra di una scheda, arrotondando gli angoli come sezioni di un cerchio 
con un diametro di 10 pixel: 

void __fastcall TForml: :FormPaint (TObject *Sender) 
{ 

Canvas->RoundRect (0, 0, ClientWidth/2, ClientHeight/2 , 10, 10); 

} 

Disegno di poligoni 

Per disegnare un poligono con un numero qualsiasi di lati su un canvas, si deve 
chiamare il suo metodo Polygon. 

Polygon accetta come unico parametro un array di punti. Questi vengono collegati 
con la penna, e l'ultimo punto viene collegato al primo per chiudere il poligono. 
Dopo aver disegnato le linee, Polygon usa il pennello per riempire l'area all'interno 
del poligono. 

Ad esempio, il codice seguente disegna un triangolo rettangolo nella meta inferiore 
sinistra di una scheda: 

void __fastcall TForml: :FormPaint (TObject *Sender) 

{ 

TPoint vertices [3] ; 
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vertices [0] = Point (0, 0) ; 
vertices [1] = Point (0, ClientHeight) ; 
vertices [2] = Point (ClientWidth, ClientHeight ) ; 
Canvas->Polygon (vertices, 2) ; 

} 

Gestione di piu oggetti di disegno in un'applicazione 



Normalmente, i vari metodi di disegno (rettangolo, figura, linea, e cosi via) sono 
disponibili nella barra strumenti e nel riquadro dei pulsanti. Le applicazioni possono 
rispondere ai clic sui pulsanti di scelta rapida per impostare gli oggetti di disegno 
desiderati. Questa sezione illustra i seguenti argomenti: 

• Come tenere la traccia dello strumento di disegno da usare. 

• Modifica dello strumento con i pulsanti di scelta rapida. 

• Uso degli strumenti di disegno. 

Come tenere la traccia dello strumento di disegno da usare 

Un programma grafico ha la necessita di tenere la traccia del tipo di strumento di 
disegno (come una linea, un rettangolo, un'ellisse o un rettangolo arrotondato) che 
un utente pud aver bisogno di usare in un istante ben precise Di solito, si dovrebbe 
usare il tipo enumerativo di C++ per elencare gli strumenti disponibili. Poiche un 
tipo enumerativo e anche una dichiarazione di tipo, e possibile sfruttare il controllo 
sui tipi di C++ per essere certi di assegnare solo quei valori specifici. 

Per esempio, il codice seguente dichiara un tipo enumerativo per ogni strumento di 
disegno disponibile in un'applicazione grafica: 

typedef enum {dtLine, dtRectangle, dtEllipse, dtRoundRect} TDrawingTool; 

A una variabile di tipo TDrawingTool puo essere assegnata solo una delle costanti 
dtLine, dtRectangle, dtEllipse o dtRoundRect. 

Per convenzione, gli identificatori di tipo iniziano con la lettera T, mentre i gruppi di 
costanti simili (come quelle che costituiscono un tipo enumerativo) iniziano con un 
prefisso di due lettere (come dt per "drawing tool"). 

Nel codice seguente, un campo aggiunto ad una scheda tiene traccia dello strumento 
di disegno usato: 

enum TDrawingTool {dtLine, dtRectangle, dtEllipse, dtRoundRect}; 

class TForml : public TForm 
{ 

__published: // IDE-managed Components 
void __fastcall FormMouseDown(TObject *Sender, TMouseButton Button, 
TShiftState Shift, int X, int Y) ; 

void __fastcall FormMouseMove(TObject *Sender, TShiftState Shift, int X, 
int Y) ; 

void __fastcall FormMouseUp (TObject *Sender, TMouseButton Button, 
TShiftState Shift, int X, int Y) ; 
private:// User declarations 
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public:// User declarations 
__fastcall TForml (TComponent* Owner); 
bool Drawing; //field to track whether button was pressed 
TPoint Origin, MovePt; // fields to store points 
TDrawingTool DrawingTool; // field to hold current tool 

}; 

Modifies degli strumenti con i pulsanti di scelta rapida 

Ogni strumento di disegno ha bisogno di un gestore di evento OnClick associate Si 
supponga che l'applicazione abbia un pulsante della barra strumenti per ciascuno dei 
quattro strumenti di disegno: linea, rettangolo, ellisse e rettangolo arrotondato. 
Occorrera collegare i seguenti gestori di evento agli eventi OnClick dei quattro 
pulsanti degli strumenti di disegno, impostando DrawingTool al valore appropriato 



per ciascuno di loro: 

void __fastcall TForml: :LineButtonClick(TObject *Sender) // 


LineButton 


DrawingTool = 


dtLine; 




void __fastcall 


TForml: :RectangleButtonClick(TObject *Sender 


// RectangleButton 


DrawingTool = 


dtRectangle; 




void __fastcall 


TForml: :EllipseButtonClick (TObject *Sender) 


// EllipseButton 


DrawingTool = 


dtEllipse; 




void __fastcall 


TForml: :RoundedRectButtonClick (TObject *Sender) // RoundRectBtn 


DrawingTool = 


dtRoundRect; 





Uso degli strumenti di disegno 

Ora che si e in grado di stabilire quale strumento usare, bisogna indicare come 
disegnare le diverse figure. Gli unici metodi che eseguono qualsiasi disegno sono i 
gestori mouse-move e mouse-up, mentre il codice disegna solo linee, 
indipendentemente dallo strumento selezionato. 

Per usare i strumenti di disegno diversi, il codice ha bisogno che venga specificato 
come disegnare, sulla base alio strumento selezionato. Si deve aggiungere questa 
istruzione al gestore di evento di ciascuno strumento. 

In questa sezione vengono trattati i seguenti argomenti: 

• Disegno di figure. 

• Condivisione del codice tra i gestori di evento. 

Disegno di figure 

Disegnare figure e facile quanto disegnare linee. Per tracciarne una e sufficiente una 
singola istruzione; sono necessarie solo le coordinate. 
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II codice seguente e una riscrittura del gestore di evento OnMousellp che disegna 
figure per tutti e quattro gli strumenti: 

void __fastcall TForml: :FormMouseUp (TObject *Sender, TMouseButton Button, 

TShiftState Shift, int X, int Y) { 

switch (DrawingTool) 
{ 

case dtLine: 

Canvas ->MoveTo (Origin. x, Origin. y) ; 

Canvas ->LineTo(X, Y) ; 

break ; 
case dtRectangle: 

Canvas->Rectangle(Origin.x, Origin. y, X, Y) ; 

break ; 
case dtEllipse: 

Canvas->Ellipse(Origin.x, Origin. y, X, Y) ; 

break ; 
case dtRoundRect : 

Canvas->Rectangle(Origin.x, Origin. y, X, Y, (Origin. x - 1)12, 
(Origin. y - Y)/2); 

break ; 

} 

Drawing = false; 

} 

Naturalmente, occorre anche aggiornare il gestore OnMouseMove per disegnare 
figure: 

void __fastcall TForml: :FormMouseMove (TObject *Sender, TMouseButton Button, 
TShiftState Shift, int X, int Y) 

{ 

if (Drawing) 
{ 

Canvas->Pen->Mode = pmNotXor; // use XOR mode to draw/erase 

switch (DrawingTool) 

{ 

case dtLine: 

Canvas->MoveTo (Origin. x, Origin. y) ; 

Canvas ->LineTo (MovePt .x, MovePt .y) ; 

Canvas->MoveTo (Origin. x, Origin. y) ; 

Canvas->LineTo(X, Y) ; 

break ; 
case dtRectangle: 

Canvas->Rectangle (Origin. x, Origin. y, MovePt. x, MovePt.y); 

Canvas->Rectangle(Origm.x, Origin. y, X, Y) ; 

break ; 
case dtEllipse: 

Canvas->Ellipse(Origin.x, Origin. y, MovePt. x, MovePt.y); 

Canvas->Ellipse(Origin.x, Origin. y, X, Y) ; 

break ; 
case dtRoundRect: 

Canvas->Rectangle(Origm.x, Origin. y, MovePt. x, MovePt.y, 

(Origin. x - MovePt. x) /2, (Origin. y - MovePt.y) 12) ; 

Canvas->Rectangle(Origin.x, Origin. y, X, Y, 

(Origin. x - 1)12, (Origin. y - Y)/2); 
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break ; 

} 

MovePt = Point (X, Y) ; 

} 

Canvas->Pen->Mode = pmCopy; 

} 

Normalmente, tutto il codice ripetitivo dell'esempio sopra riportato dovrebbe essere 
inserito in una routine separata.La sezione successiva mostra tutto il codice per il 
disegno delle figure in una singola routine che i gestori di evento del mouse possono 
chiamare. 

Condivisione del codice tra gestori di evento 

Quando ci si rende conto del fatto che molti gestori di evento usano lo stesso codice, 
si puo rendere l'applicazione piu efficiente spostando il codice ripetuto in una 
routine che tutti i gestori di evento possono condividere. 

Per aggiungere un metodo ad una scheda: 

1 Aggiungere la dichiarazione del metodo all'oggetto scheda. 

La dichiarazione puo essere aggiunta nelle parti public o private alia fine della 
dichiarazione dell'oggetto scheda. Se il codice condivide solo i dettagli di gestione 
di alcuni eventi, probabilmente e piu sicuro rendere il metodo condiviso private. 

2 Scrivere l'implementazione del metodo nel file .cpp della unit della scheda. 

L'header per l'implementazione del metodo deve corrispondere esattamente alia 
dichiarazione, con gli stessi parametri nello stesso ordine. 

II codice seguente aggiunge alia scheda un metodo DrawShape, che viene chiamato da 
ciascuno dei gestori. Innanzi tutto, la dichiarazione di DrawShape viene aggiunta alia 
dichiarazione dell'oggetto scheda: 

enum TDrawingTool {dtLine, dtRectangle, dtEllipse, dtRoundRect } ; 

class TForml : public TForm 
{ 

__published: // IDE-managed Components 

void fastcall FormMouseDown(TObject *Sender, TMouseButton Button, 

TShiftState Shift, int X, int Y) ; 

void __fastcall FormMouseMove(TObject *Sender, TShiftState Shift, int X, 
int Y) ; 

void __fastcall FormMouseUp (TObject *Sender, TMouseButton Button, 

TShiftState Shift, int X, int Y) ; 
private:// User declarations 

void __fastcall DrawShape (TPoint TopLeft, TPoint BottomRight, TPenMode AMode) ; 
public:// User declarations 

__fastcall TForml (TComponent* Owner); 

bool Drawing; //field to track whether button was pressed 
TPoint Origin, MovePt; // fields to store points 
TDrawingTool DrawingTool; // field to hold current tool 

}; 
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Quindi, l'implementazione di DrawShape viene scritta nel file .cpp della unit della 
scheda: 

void __fastcall TForml: : DrawShape (TPoint TopLeft, TPoint BottomRight, 
TPenMode Mode) 

{ 

Canvas->Pen->Mode = AMode; 
switch (DrawingTool) 
{ 

case dtLine: 

Canvas ->MoveTo (TopLeft .x, TopLeft .y) ; 

Canvas ->LineTo (BottomRight .x, BottomRight .y) ; 

break ; 
case dtRectangle: 

Canvas->Rectangle (TopLeft .x, TopLeft. y, BottomRight .x, BottomRight .y) ; 
break ; 
case dtEllipse: 

Canvas->Ellipse(TopLeft.x, TopLeft. y, BottomRight .x, BottomRight .y) ; 
break ; 
case dtRoundRect: 

Canvas->Rectangle (TopLeft .x, TopLeft. y, BottomRight .x, BottomRight .y, 

(TopLeft. x - BottomRight. x)/2, (TopLeft. y - BottomRight .y) 12) ; 

break ; 

} 

} 

Gli altri gestori di evento vengono modificati per chiamare DrawShape. 

void __fastcall TForml: :FormMouseUp (TObject *Sender) 

{ 

DrawShape (Origin, Point (X,Y), pmCopy) ; // draw the final shape 
Drawing = false; 

} 

void __fastcall TForml: :FormMouseMove(TObject *Sender, TMouseButton Button, 
TShiftState Shift, int X, int Y) 

{ 

if (Drawing) 

{ 

DrawShape (Origin, MovePt, pmNotXor) ; // erase previous shape 
MovePt = Point (X, Y) ; 

DrawShape (Origin, MovePt, pmNotXor); // draw current shape 

} 

} 

Disegno su un grafico 



Non sono necessari componenti per manipolare gli oggetti grafici dell'applicazione. 
E possibile costruire, prelevare, salvare e distruggere oggetti grafici senza dover 
necessariamente disegnare qualcosa sullo schermo. Infatti, raramente le applicazioni 
disegnano direttamente su una scheda. Piu spesso un'applicazione opera sui grafici e 
poi utilizza un componente controllo immagine per visualizzare il grafico su una 
scheda. 
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Una volta spostato il disegno dell'applicazione nel grafico del controllo immagine, e 
facile aggiungere le funzioni di stampa, di clipboard, di caricamento e salvataggio 
per tutti gli oggetti grafici. Gli oggetti grafici possono essere file bitmap, metafile, 
icone o qualsiasi altra classe di grafici installati, come, ad esempio, i grafici jpeg. 

Poiche si disegna su un'immagine fuori schermo come un canvas TBitmap, 
l'immagine non viene visualizzata finche un controllo non copia da una bitmap sul 
canvas del controllo. Cioe, quando si disegnano bitmap e si assegnano ad un controllo 
immagine, l'immagine appare solo quando il controllo ha l'opportunita per elaborare 
il messaggio Paint. Se, invece, si disegna direttamente sulla proprieta canvas di un 
controllo, l'oggetto Picture viene visualizzato immediatamente. 

Come far scorrere i grafici 

II grafico non deve avere le stesse dimensioni della scheda: puo essere piu piccolo o 
piu grande. Aggiungendo alia scheda un controllo casella di scorrimento e 
collocando l'immagine grafica al suo interno, e possibile visualizzare grafici che sono 
piu grandi della scheda o addirittura piu grandi dello schermo. Per aggiungere un 
grafico con scorrimento, occorre prima aggiungere un componente TScrollBox e 
quindi aggiungere il controllo immagine. 

Aggiunta di un controllo immagine 

Un controllo immagine e un componente contenitore che consente di visualizzare 
oggetti Bitmap. Un controllo immagine serve per contenere una bitmap che non 
necessariamente viene visualizzata sempre, o che un'applicazione ha bisogno di 
usare per generare altre figure. 

II paragrafo" Aggiunta di grafici ai controlli" a pagina 6-12 illustra come usare i 
grafici nei controlli. 

Collocazione del controllo 

Un controllo immagine puo essere collocato in qualsiasi punto di una scheda. Se si 
desidera sfruttare la capacita del controllo immagine di autodimensionarsi in 
funzione della figura, occorre impostare solo l'angolo superiore sinistra. Se il 
controllo immagine e un contenitore non visibile per una bitmap, si puo collocarlo in 
un punto qualsiasi, proprio come se fosse un componente non visuale. 

Se si rilascia il controllo immagine su una casella di scorrimento gia allineata all'area 
client della scheda, cio garantisce che la casella aggiungera tutte le barre di 
scorrimento necessarie per accedere alle parti fuori schermo dell'immagine. Dopo di 
che si deve impostare la proprieta del controllo immagine. 

Impostazione delle dimensioni iniziali della bitmap 

Quando si colloca un controllo immagine, questo e solo un contenitore. Tuttavia, in 
fase di progettazione, e possibile impostare la proprieta Picture del controllo 
immagine in modo da contenere un grafico statico. II controllo puo caricare la sua 
immagine da un file anche in fase di esecuzione, come descritto nel paragrafo 
"Caricamento e salvataggio dei file grafici" a pagina 10-20. 
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Per creare una bitmap vuota quando viene avviata l'applicazione: 

1 Collegare un gestore all'evento OnCreate per la scheda che contiene rimmagine. 

2 Creare un oggetto Bitmap, e assegnarlo alia proprieta Picture->Graphic del 
controllo immagine. 

In questo esempio l'immagine si trova nella scheda principale dell'applicazione, 
Forml, cosicche il codice collega un gestore all'evento OnCreate di Forml: 

void __fastcall TForml: :FormCreate(TObject *Sender) 
{ 

Graphics : :TBitmap *Bitmap = new Graphics : :TBitmap () ; // create the bitmap object 
Bitmap->Width = 200; // assign the initial width... 

Bitmap->Height = 200; // ...and the initial height 

Image->Picture->Graphic = Bitmap; // assign the bitmap to the image control 
delete Bitmap; // free the bitmap object 

} 

L'assegnazione della bitmap alia proprieta Graphic dell'oggetto picture copia la 
bitmap nell'oggetto Picture. Tuttavia, l'oggetto immagine non assume la proprieta 
della bitmap, e pertanto, dopo avere fatto l'assegnazione, sara necessario liberarlo. 

Se a questo punto si esegue l'applicazione, l'area client della scheda avra una regione 
bianca, che rappresenta la bitmap. Se le finestra viene dimensionata in modo che 
l'area client non possa visualizzare l'intera immagine, la casella di scorrimento 
mostrera automaticamente le barre di scorrimento per consentire la visualizzazione 
del resto dell'immagine. Ma, se si cerca di disegnare sull'immagine, non si ottiene 
alcun grafico, perche l'applicazione sta ancora disegnando sulla scheda, che ora si 
trova dietro l'immagine e la casella di scorrimento. 

Disegno sulla bitmap 

Per disegnare su una bitmap, si deve usare il canvas del controllo immagine e 
collegare i gestori di evento del mouse a quelli corrispondenti del controllo immagine. 
Di solito, si utilizzeranno operazioni di regione (riempienti, rettangoli, spezzate e cosi 
via). Questi sono metodi di disegno rapidi ed efficaci. 

Un modo efficiente per disegnare immagini quando si ha bisogno di accedere ai 
singoli pixel, consiste nel ricorrere alia proprieta ScanLine della bitmap. Per un uso 
generico, e possibile impostare il formato dei pixel della bitmap a 24 bit e quindi 
trattare il puntatore restituito da ScanLine come un array di RGB. Altrimenti, sara 
necessario conoscere il formato nativo della proprieta ScanLine. Questo esempio 
mostra come usare ScanLine per ricevere i pixel una riga alia volta. 

void __fastcall TForml: :ButtonlClick(TObject *Sender) 

{ 

Graphics : :TBitmap *pBitmap = new Graphics : :TBitmap () ; 
// This example shows drawing directly to the Bitmap 
Byte *ptr; 
try 

{ 

pBitmap->LoadFromFile ( "C: WProgram Files\\Borland\\CBuilder\\Images\\Splash\\256color\\ 
factory.bmp " ) ; 

for (int y = 0; y < pBitmap->Height ; y++) 

{ 
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ptr = pBitmap->ScanLine[y] ; 
for (int x = 0; x < pBitmap->Width; x++) 
ptr[x] = (Byte)y; 

} 

Canvas - >Draw(0 , 0.pBitmap) ; 

} 

catch (...) 

{ 

ShowMessagel "Could not load or alter bitmap"); 

} 

delete pBitmap; 

} 

Nel caso di applicazioni multipiattaforma, modificare il codice specifico per 
Windows e per la VCL in modo che l'applicazione possa esere eseguita in ambiente 
Linux. Ad esempio, nei nomi dei percorsi in Linux si utilizza come delimitatore una 
barra diritta. Per ulteriori informazioni sulle applicazioni CLX e multipiattaforma , 
vedere il Capitolo 14, "Sviluppo di applicazioni multipiattaforma". 

Caricamento e salvataggio dei file grafici 



Le immagini grafiche che esistono solo per la durata dell'esecuzione di 
un'applicazione hanno un valore molto limitato. Spesso, si preferisce usare la stessa 
figura ogni volta o salvare una figura creata per usarla successivamente. II 
componente image facilita il caricamento delle immagini da un file e il loro 
salvataggio. 

I componenti usati per caricare, salvare e sostituire immagini grafiche supportano 
molti formati grafici, compresi i file bitmap, i metafiles, i glifi, e cosi via. Essi 
supportano anche le classi grafiche installabili. 

II modo di caricare e di salvare i file grafici e simile a quello di qualsiasi altro file e 
viene descritto nelle seguenti sezioni: 

• Caricamento di un'immagine da un file. 

• Salvataggio di un'immagine in un file. 

• Sostituzione dell'immagine. 

Caricamento di un'immagine da un file 

L'applicazione deve fornire la possibility di caricare un'immagine da un file se ha 
bisogno di modificarla o se si desidera memorizzarla in un file esterno, in modo che 
un utente o un'altra applicazione possa modificarla. 

Per caricare un file grafico in un controllo immagine, si deve chiamare il metodo 
LoadFromFile dell'oggetto Picture del controllo immagine. 

II codice seguente riceve un nome di file da una finestra di dialogo per l'apertura dei 
file, e quindi carica quel file in un controllo immagine di nome Image: 

void __fastcall TForml: :0penlClick(T0bject *Sender) 
{ 

if (OpenPictureDialogl->Execute() ) 
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{ 

CurrentFile = OpenPictureDialogl->FileName; 
Image->Picture->LoadFromFile (CurrentFile) ; 

} 

} 

Salvataggio di un'immagine in un file 

L'oggetto Picture della libreria VCL puo caricare e salvare grafici in diversi formati, 
ed e possibile creare e registrare propri formati di file grafici, in modo che gli oggetti 
picture possano caricarli e memorizzarli. 

Per salvare il contenuto di un controllo immagine in un file, si deve chiamare il 
metodo SaveToFile dell'oggetto Picture del controllo immagine. 

II metodo SaveToFile richiede il nome del file da salvare. Se l'immagine e stata appena 
creata, e probabile che non abbia un nome di file; oppure, puo darsi che un utente 
voglia salvare una figura esistente in un altro file. In ogni caso l'applicazione ha 
bisogno di ricevere un nome di file dall'utente prima del salvataggio, come viene 
mostrato nella successiva sezione. 

La seguente coppia di gestori di evento, collegata rispettivamente alle voci di menu 
File I Save e File I Save As, gestisce il nuovo salvataggio dei file ai quali e gia stato 
assegnato un nome, dei file ancora senza nome e dei file esistenti con nomi nuovi. 

void __fastcall TForml: :SavelClick(TOb]ect *Sender) 

{ 

if (! CurrentFile. IsEmptyO ) 
lmage->Picture->SaveToFile (CurrentFile) ; // save if already named 
else SaveAslClick (Sender) ; // otherwise get a name 

} 

void __fastcall TForml: :SaveAslClick(TObject *Sender) 
{ 

if (SaveDialogl->Execute ( ) ) // get a file name 

{ 

CurrentFile = SaveDialogl->FileName; // save user-specified name 
SavelClick ( Sender) ; // then save normally 

} 

} 

Sostituzione dell'immagine 

In qualsiasi momento e possibile sostituire la e figura di un controllo immagine. Se si 
assegna un nuovo grafico ad un'immagine che ne ha gia uno, il nuovo grafico 
sostituisce quello esistente. 

Per sostituire la figura di un controllo immagine, si deve assegnare un nuovo grafico 
all'oggetto Picture del controllo immagine. 

II processo adottato per la creazione del nuovo grafico e identico a quello utilizzato 
per creare il grafico iniziale (consultare "Impostazione delle dimensioni iniziali della 
bitmap" a pagina 10-18), ma in questo caso si deve fornire anche un modo che 
consenta alperche l'utente di scegliere una dimensione diversa da quella standard 
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usata per il grafico iniziale. Un semplice modo per fornire questa opzione consiste 
nel presentare una finestra di dialogo, come quella della Figura 10.1. 

Figura 10.1 Finestra di dialogo Bitmap Dimension dalla unit BMPDIg 



Bitmap Dimensions 
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X Cancel 
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Questa particolare finestra di dialogo viene creata nella unit BMPDIg che fa parte del 
progetto GraphEx (nella directory EXAMPLES \ DOC \GRAPHEX). 

Avendo questa finestra di dialogo nel progetto, aggiungere un'istruzione include 
relativa a BMPDlg.hpp nel file .cpp della scheda principale. Quindi, si puo collegare 
un gestore all'evento onCHck della voce di menu File I New. Ecco un esempio: 

void __fastcall TForral: :NewlClick(TObject *Sender) 
{ 

Graphics : :TBitmap *Bitmap; 
// make sure focus is on width field 

NewBMPForm->ActiveControl = NewBMPForm->WidthEdit ; 
// initialize to current dimensions as default ... 

NewBMPForm->WidthEdit->Iext = IntToStr (Image->Picture->Graphic->Width) ; 
NewBMPForm->HeightEdit->Text = IntToStr (Image->Picture->Graphic->Height ) ; 
if (NewBMPForm->ShowModal ( ) != IDCANCEL) { // if user does not cancel dialog... 

Bitmap = new Graphics : :TBitmap () ; // create a new bitmap object 

// use specified dimensions 

Bitmap->Width = StrToInt (NewBMPForm->WidthEdit->Text) ; 
Bitmap->Height = StrToInt (NewBMPForm->HeightEdit->Text) ; 

Image->Picture->Graphic = Bitmap; // replace graphic with new bitmap 

CurrentFile = EmptyStr; //indicate unnamed file 

delete Bitmap; 



L'assegnazione di una nuova bitmap alia proprieta Graphic dell'oggetto Picture 
provoca la copia del nuovo grafico nell'oggetto ma l'oggetto non ne prende possesso. 
L'oggetto Picture gestisce il proprio oggetto grafico interno. . A causa di cio, il codice 
precedente libera l'oggetto bitmap dopo avere fatto l'assegnazione. 



Uso della clipboard con i grafici 



E possibile usare la clipboard di Windows per copiare e incollare grafici all'interno 
delle applicazioni o per scambiare grafici con altre applicazioni. L'oggetto Clipboard 
della VCL semplifica la gestione di diversi tipi di informazione, compresi i grafici. 

Prima di poter usare l'oggetto clipboard nell'applicazione, e necessario aggiungere 
ad ogni file .cpp che dovra accedere ai dati della clipboard un'istruzione include per 
il file Clipbrd.hpp. 
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Per le applicazioni multipiattaforma, i dati memorizzati nella clipboard utilizzando 
la CLX vengono memorizzati come un tipo MIME a cui e associato un oggetto 
TStream. Nella CLX sono previste le seguenti costanti predefinite per i tipi MIME 



seguenti. 




Tabella 10.4 Tipi MIME e costanti della CLX 




Tipo MIME 


Costante CLX 


'image/ delphi.bitmap' 


SDelphiBitmap 


'image/ delphi.component' 


SDelphiComponent 


'image/ delphi.picture' 


SDelphiPicture 


'image/ delphi.drawing' 


SDelphiDrawing 



Operazioni di copia di grafici nella clipboard 

Nella clipboard e possibile copiare qualsiasi immagine, compreso il contenuto dei 
controlli image. Una volta nella clipboard, l'immagine e disponibile per tutte le 
applicazioni. 

Per copiare un'immagine nella clipboard, bisogna assegnarla all'oggetto clipboard 
usando il metodo Assign. 

Questo codice mostra come copiare un'immagine da un controllo immagine di nome 
Image nella clipboard in risposta ad un clic sulla voce di menu Edit I Copy: 

void __fastcall TForml: :CopylClick(TObject *Sender) 

{ 

Clipboard ( ) ->Assign(Image->Picture) ; 

} 

Operazioni di taglio di grafici nella clipboard 

Le operazioni di taglio di un grafico negli Appunti sono analoghe alle operazioni di 
copia, con la differenza che il grafico viene eliminato dalla sorgente. 

Per tagliare un grafico da una figura nella clipboard, occorre prima copiarlo nella 
clipboard, quindi si deve eliminare l'originale. 

Nella maggioranza dei casi l'unico problema nel taglio e come mostrare che 
l'immagine originale e stata eliminata. L'impostazione dell'area sul colore bianco e 
una soluzione diffusa, come viene mostrato nel codice seguente che collega un 
gestore all'evento OnClick della voce di menu Edit I Cut: 

void __fastcall TForml: :CutlClick(TObject *Sender) 
{ 

TRect ARect; 

CopylClick ( Sender) ; // copy picture to clipboard 

Image->Canvas->CopyMode = cmWhiteness; // copy everything as white 
ARect = Rect(0, 0, lmage->Width, lmage->Height) ; // get dimensions of image 
Image->Canvas->CopyRect (ARect, Image ->Canvas, ARect); // copy bitmap over self 
Image->Canvas->CopyMode = cmSrcCopy; // restore default mode 

} 
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Operazioni di incollaggio di grafici dalla clipboard 

Se la clipboard contiene un grafico bitmap, e possibile incollarlo in qualsiasi oggetto 
immagine, compresi i controlli immagine e la superficie di una scheda. 

Per incollare un grafico dalla clipboard: 

1 Chiamare il metodo HasFormat della clipboard (se si usa la VCL) oppure il metodo 
Provides (se si usa la CLX) per controllare se contiene un'immagine grafica. 

HasFormat (o Provides in CLX) e una funzione Boolean. Restituisce true se la 
clipboard contiene un elemento del tipo specificato nel parametro. Per verificare se 
c'e un grafico in ambiente Windows, basta passare CF_BITMAP. In applicazioni 
multipiattaforma, si passa SDelphiBitmap. 

2 Assegnare la clipboard alia destinazione. 

Questo codice mostra come incollare una figura dalla clipboard in un controllo 
immagine in risposta ad un clic su una voce di menu Edit I Paste: 

void __fastcall TForml: :PastelClick(TObject *Sender) 

{ 

Graphics : :TBitmap *Bitmap; 
if (Clipboard! )->HasFormat(CF_BlTMAP) ) { 
Imagel->Picture->Bitmap->Assign (Clipboard!) ) ; 

} 

} 

Lo stesso esempio in un programma CLX multipiattaforma sarebbe simile al 
seguente: 

void __fastcall TForml: :PastelClick(TObject *Sender) 

{ 

QGraphics : :TBitmap *Bitmap; 
if (Clipboard) ) ->Provides (SDelphiBitmap) ) { 
Imagel->Picture->Bitmap->Assign (Clipboard () ) ; 

} 

} 

II grafico nela clipboard puo provenire da questa applicazione, oppure potrebbe 
anche essere stato copiato da un'altra applicazione, come Microsoft Paint. In questo 
caso non e necessario controllare il formato della clipboard, in quanto il menu Paste 
viene disattivato quando la clipboard non contiene un formato supportato. 

Esempio di effetto elastico 



Questo esempio descrive i dettagli implementativi dell'effetto "elastico" in 
un'applicazione grafica che segue la traccia dei movimenti del mouse, man mano che 
l'utente disegna un grafico in fase di esecuzione. II codice di esempio riportato in 
questa sezione e tratto da un'applicazione di esempio collocata nella directory 
Examples\Doc\GraphEx. L'applicazione disegna linee e figure nel canvas di una 
finestra in risposta ai clic e alle operazioni di trascinamento: la pressione di un 
pulsante del mouse button avvia il disegno, mentre il suo rilascio ne determina la 
fine. 
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All'inizio, il codice di esempio mostra come disegnare sulla superficie della scheda 
principale. Gli esempi successivi mostrano come disegnare su una bitmap. 

I seguenti argomenti descrivono l'esempio: 

• Risposta al mouse. 

• Aggiunta di un campo ad un oggetto scheda per seguire le tracce delle azioni del 
mouse. 

• Affinamento del disegno delle linee. 

Risposta al mouse 

L'applicazione puo rispondere alle azioni del mouse: pulsante-mouse giu, 
spostamento mouse e pulsante-mouse su. Essa puo rispondere anche ad un clic 
(un'operazione completa di pressione e rilascio nello stesso punto), che puo essere 
generato da una combinazione di tasti (come le pressione di Invio in una finestra di 
dialogo modale). 

In questa sezione vengono trattati i seguenti argomenti: 

• Cosa c'e in un evento mouse. 

• Risposta ad un'azione pulsante mouse giu. 

• Risposta ad un'azione mouse-su. 

• Risposta ad uno spostamento del mouse. 

Cosa c'e in un evento mouse?? 

C++Builder ha tre eventi mouse: OnMouseDown,OnMouseMove e OnMousellp. 

Quando un'applicazione rileva un'azione del mouse, chiama il gestore di evento che 
e stato definito per l'evento corrispondente, passando cinque parametri. Le 
informazioni di questi parametri devono essere utilizzate per personalizzare le 
risposte agli eventi. I cinque parametri sono i seguenti: 



Tabella 10.5 


Parametri degli eventi mouse 


Parametro 




Sender 


L'oggetto che ha rilevato l'azione del mouse 


Button 


Indica quale pulsante del mouse e stato coinvolto: mbLeft, mbMiddle, or mbRight 


Shift 


Indica lo stato dei tasti Alt, Ctrl, e Maisc al momento dell'azione del mouse 


X,Y 


Le coordinate del punto in cui si e verificato l'evento 



Nella maggioranza dei casi le coordinate devono essere passate ad un gestore di 
evento del mouse, ma talvolta e anche necessario controllare Button per determinare 
quale pulsante del mouse ha causato l'evento. 

C++Builder usa gli stessi criteri di Microsoft Windows nel determinare quale 
pulsante del mouse e stato premuto. Pertanto, se sono stati invertiti i pulsanti del 
mouse predefiniti "principale" e "secondario" (in modo che il pulsante destro sia 
quello principale), un clic sul pulsante principale (destro) registrera mbLeft come 
valore del parametro Button. 
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Risposta ad un'azione mouse-down 

Ogni volta che l'utente preme un pulsante sul mouse, l'oggetto sul quale si trova il 
puntatore riceve un evento OnMouseDown. L'oggetto quindi puo rispondere 
all'evento. 

Per rispondere ad un'azione mouse-down, si deve collegare un gestore all'evento 
OnMouseDown. 

C++Builder genera un gestore vuoto per un evento mouse-down sulla scheda: 

void fastcall TForml: :FormMouseDown (TObject *Sender, TMouseButton Button, 

TShiftState Shift, int X, int Y) 

{ 
} 

Risposta ad un'azione mouse-down 

II codice seguente visualizza sulla scheda la stringa 'Here!' alia posizione in cui e 
stato fatto clic con il mouse: 

void fastcall TForml: :FormMouseDown (TObject *Sender, TMouseButton Button, 

TShiftState Shift, int X, int Y) 

{ 

Canvas->TextOut (X, Y, "Here!");// write text at (X, Y) 

} 

Durate l'esecuzione dell'applicazione, se si porta il cursore del mouse sulla scheda e 
si preme il tasto si vedra apparire la stringa "Here!" nel punto in cui e stato fatto clic. 
II codice seguente imposta la posizione corrente di disegno alle coordinate in cui 
l'utente ha premuto il pulsante: 

void __fastcall TForml: :FormMouseDown (TObject *Sender, TMouseButton Button, 
TShiftState Shift, int X, int Y) 

{ 

Canvas->MoveTo (X, Y);// set pen position 

} 

Ora la pressione del pulsante del mouse imposta la posizione della penna, definendo 
il punto iniziale della linea. Per disegnare una linea fino al punto in cui l'utente 
rilascia il pulsante, si deve rispondere ad un evento mouse-up. 

Risposta ad un'azione mouse-up 

Ogni volta che l'utente rilascia un pulsante del mouse si verifica un evento 
OnMousellp. Solitamente l'evento va all'oggetto sul quale si trova il cursore del 
mouse quando l'utente preme il pulsante, che non e necessariamente lo stesso 
oggetto sul quale si trova il cursore quando il pulsante viene rilasciato. Cio consente, 
per esempio, di disegnare una linea come se si estendesse oltre il bordo della scheda. 

Per rispondere alle azioni mouse-up, si deve definire un gestore per l'evento 
OnMousellp. 

II codice seguente e un semplice gestore di evento OnMousellp che disegna una linea 
fino al punto di rilascio del pulsante del mouse: 

void __fastcall TForml: :FormMouseUp (TObject *Sender, TMouseButton Button, 
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TShiftState Shift, int X, int Y) 

{ 

Canvas->LineTo(X, Y) ,7/ draw line from PenPos to (X, Y) 

} 

Questo codice permette ad un utente di disegnare linee facendo clic, trascinando e 
rilasciando. In questo caso, l'utente non puo vedere la linea finche il pulsante del 
mouse non viene rilasciato. 

Risposta ad uno spostamento del mouse 

Quando l'utente sposta il mouse, si verifica periodicamente un evento OnMouseMove. 
L'evento va all'oggetto che era sotto il puntatore del mouse quando l'utente ha 
premuto il pulsante. Questo consente di dare all'utente un controllo intermedio 
disegnando linee temporanee mentre si sposta il mouse. 

Per rispondere ai movimenti del mouse, occorre definire un gestore per l'evento 
OnMouseMove. Questo esempio usa gli eventi mouse-move per disegnare figure 
intermedie su una scheda mentre l'utente tiene premuto il pulsante del mouse, 
fornendo pertanto all'utente un certo controllo. II gestore di evento OnMouseMove 
disegna una linea su una scheda nella posizione dell'evento OnMouseMove: 

void __fastcall TForml: :FormMouseMove (TObject *Sender, TMouseButton Button, 
TShiftState Shift, int X, int Y) 

{ 

Canvas->LineTo (X, Y) ,7/ draw line to current position 

} 

Con questo codice, lo spostamento del mouse sulla scheda fa si che il disegno segua il 
mouse, anche prima che il pulsante del mouse venga premuto. 

Gli eventi mouse-move si verificano quando non sono stati premuti i pulsanti del 
mouse. 

Se si vuole tenere traccia del fatto che sia stato premuto un pulsante del mouse, 
occorre aggiungere un campo oggetto all'oggetto scheda. 

Aggiunta di un campo ad un oggetto scheda per tenere traccia delle azioni del 
mouse 

Per tenere traccia del fatto che sia stato premuto o meno un pulsante del mouse, 
occorre aggiungere un campo oggetto all'oggetto scheda. Quando ad una scheda 
viene aggiunto un componente, C++Builder aggiunge all'oggetto scheda un campo 
che rappresenta quel componente, in modo che sia possibile fare riferimento al 
componente tramite il nome del campo. Inoltre, si possono aggiungere alia scheda 
campi propri modificando la dichiarazione di tipo nel file header della scheda. 

Nell'esempio seguente la scheda ha bisogno di registrare se l'utente ha premuto un 
pulsante del mouse. Per farlo, essa aggiunge un campo booleana e ne imposta il 
valore quando l'utente preme il pulsante del mouse. 

Per aggiungere un campo ad un oggetto, si deve modificare la definizione di tipo 
dell'oggetto, specificando l'identificatore di campo e il tipo dopo la direttiva public 
in fondo alia dichiarazione. 
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CC++Builder "possiede" qualsiasi dichiarazione prima della direttiva public: questo 
e il punto in cui vengono immessi i campi che rappresentano i controlli e i metodi che 
rispondono agli eventi. 

II codice seguente da ad una scheda un campo di nome Drawing di tipo bool, nella 
dichiarazione dell'oggetto scheda. Inoltre, aggiunge due campi per memorizzare i 
punti Origin e MovePt di tipo TPoint. 

class TForml : public TForm 
{ 

__published: // IDE-managed Components 
void __fastcall FormMouseDown (TObject *Sender, TMouseButton Button, 
TShiftState Shift, int X, int Y) ; 

void __fastcall FormMouseMove (TObject *Sender, TShiftState Shift, int X, 
int Y) ; 

void fastcall FormMouseUp (TObject *Sender, TMouseButton Button, 

TShiftState Shift, int X, int Y) ; 
private:// User declarations 
public:// User declarations 

__fastcall TForml (TComponent* Owner); 

bool Drawing; //field to track whether button was pressed 
TPoint Origin, MovePt; // fields to store points 

}; 

Se si ha un campo Drawing che registra le operazioni di disegno, impostarlo a true 
quando si preme il pulsante del mouse e a false quando lo si rilascia: 

void __fastcall TForml: : FormMouseDown (TObject *Sender, TMouseButton Button, 
TShiftState Shift, int X, int Y) 

{ 

Drawing = true; // set the Drawing flag 

Canvas->MoveTo (X, Y) ; // set pen position 

} 

void fastcall TForml: :FormMouseUp (TObject *Sender, TMouseButton Button, 

TShiftState Shift, int X, int Y) 

{ 

Canvas->LineTo (X, Y) ; // draw line from PenPos to (X, Y) 

Drawing = false; // clear the Drawing flag 

} 

Quindi, si puo modificare il gestore di evento OnMouseMove per disegnare solo 
quando Drawing e true: 

void fastcall TForml: : FormMouseMove (TObject *Sender, TMouseButton Button, 

TShiftState Shift, int X, int Y) 

{ 

if (Drawing) 

Canvas->LineTo (X, Y);// only draw if mouse is down 

} 

Questo codice genera un disegno solo tra gli eventi mouse-down e mouse-up, ma 
genera anche una linea scarabocchiata che traccia gli spostamenti del mouse anziche 
una linea retta. 

II problema e che ogni volta che il mouse si sposta, il relativo gestore di evento 
chiama LineTo, il quale sposta la posizione della penna, e nel momento in cui viene 
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rilasciato il pulsante, si perde l'indicazione del punto dal quale doveva partire la 
linea retta. 

Affinamento del disegno delle linee 

Con i campi collocati per tracciare i vari punti, e possibile rifinire il disegno di una 
linea dell'applicazione. 

Memorizzazione del punto di origine 

Quando si disegnano linee, per tener traccia del punto in cui inizia la linea si utilizza 
il campo Origin. 

Origin deve essere impostato al punto in cui si verifica l'evento mouse-down, in 
modo che il gestore di evento mouse-up possa usare Origin per indicare l'inizio della 
linea, come in questo codice: 

void fastcall TForml: :FormMouseDown (TObject *Sender, TMouseButton Button, 

TShiftState Shift, int X, int Y) 

{ 

Drawing = true; // set the Drawing flag 

Canvas->MoveTo (X, Y) ; // set pen position 

Origin = Point (X, Y) ; // record where the line starts 

} 

void fastcall TForml: :FormMouseUp (TObject *Sender, TMouseButton Button, 

TShiftState Shift, int X, int Y) 

{ 

Canvas->MoveTo (Origin. x, Origin. y); // move pen to starting point 
Canvas->LineTo (X, Y) ; // draw line from PenPos to (X, Y) 

Drawing = false; // clear the Drawing flag 

} 

Queste modifiche servono all'applicazione per disegnare di nuovo la linea finale, e 
non per disegnare delle azioni intermedie— l'applicazione non supporta ancora 
l'effetto "elastico." 

Momorizzazione dello spostamento 

II problema, almeno per come e scritto al momento il gestore di evento 
OnMouseMove, e che la linea viene disegnata fino alia posizione corrente del mouse, 
partendo dall'ultima posizione del mouse, non da quella originaria. E possibile porre 
rimedio a questo problema spostando la posizione di disegno al punto di origine, 
quindi disegnando fino al punto attuale: 

void fastcall TForml: :FormMouseMove (TObject *Sender, TMouseButton Button, 

TShiftState Shift, int X, int Y) 

{ 

if (Drawing) 
{ 

Canvas ->MoveTo (Origin. x, Origin. y); // move pen to starting point 
Canvas->LineTo(X, Y) ; 

} 

} 
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Questo codice registra la posizione attuale del mouse, ma le linee intermedie non 
scompaiono, cosicche risulta difficile vedere la linea finale. L'esempio ha bisogno di 
eliminare ogni linea prima di disegnare quella successiva, tenendo traccia di dove si 
trovava quella precedente. II campo MovePt consente di realizzare cio. 

MovePt deve essere impostato al punto finale di ciascuna linea intermedia, in modo 
che si possa usare MovePt e Origin per eliminare quella linea la volta successiva in cui 
viene disegnata una linea: 

void __fastcall TForml: :FormMouseDown (TObject *Sender, TMouseButton Button, 
TShiftState Shift, int X, int Y) 

{ 

Drawing = true; // set the Drawing flag 

Canvas->MoveTo (X, Y) ; // set pen position 
Origin = Point (X, Y) ; // record where the line starts 

MovePt = Point (X, Y) ; // record last endpoint 

} 

void fastcall TForml: :FormMouseMove (TObject *Sender, TMouseButton Button, 

TShiftState Shift, int X, int Y) 

{ 

if (Drawing) 
{ 

Canvas->Pen->Mode = pmNotXor; // use XOR mode to draw/ erase 

Canvas ->MoveTo (Origin. x, Origin. y) 
Canvas->LineTo (MovePt .x, MovePt .y) 
Canvas->MoveTo (Origin. x, Origin. y) 



// move pen to starting point 
// erase old line 

// move pen to starting point again 



Canvas->LineTo (X, Y) ; // draw new line 

} 

MovePt = Point (X, Y) ; // record new endpoint 

Canvas->Pen->Mode = pmCopy; 

} 

A questo punto, si ha a disposizione un effetto "elastico" quando si disegna la linea. 
Cambiando il modo della penna in pmNotXor, e possibile combinare la linea con i 
pixel dello sfondo. Quando si va ad eliminare la linea, in realta si reimpostano i pixel 
al modo in cui si trovavano prima. Riportando il modo della penna a pmCopy (il suo 
valore predefinito) dopo aver disegnato le linee, si ha la certezza che la penna e 
pronta per tracciare il suo disegno finale non appena si rilascia il pulsante del mouse. 



Uso di componenti multimediali 



C++Builder consente di aggiungere componenti multimediali alle applicazioni 
Windows (non CLX o per di Linus). A questo scopo, si possono usare il componente 
T Animate della pagina Win32 o il componente TMediaPlayer della pagina System 
della Component palette. Utilizzare il componente di animazione se si vuole 
aggiungere all'applicazione un video clip senza l'audio. Utilizzare il componente 
MediaPlayer, invece, per aggiungere clip audio o video a un'applicazione. 

Per ulteriori informazioni sui componenti T Animate e TMediaPlayer, consultare la 
Guida in linea della VCL. 

In questa sezione vengono trattati i seguenti argomenti: 
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• Aggiunta di clip video senza suono ad un'applicazione 

• Aggiunta di clip audio e/o video ad un'applicazione 

Aggiunta di clip video senza suono ad un'applicazione 



Animation in C++Builder consente di aggiungere all'applicazione clip video senza 
suono. 

Per aggiungere un clip video senza suono ad un'applicazione: 

1 Fare doppio clic sull'icona Animate sulla pagina Win32 della Component palette. 
Questa operazione inserisce automaticamente un controllo di animazione nella 
finestra della scheda in cui si intende visualizzare il clip video. 

2 Usando l'Object Inspector, selezionare la proprieta Name ed immettere un nuovo 
nome per il controllo di animazione. Questo nome verra usato quando si chiama il 
controllo di animazione. (Per attribuire un nome agli identificatori C++, occorre 
seguire le regole standard). 

Per impostare in fase di progettazione le proprieta e per creare i gestori di evento, 
si deve lavorare sempre direttamente nell'Object Inspector. 

3 Eseguire una delle seguenti operazioni: 

• Selezionare la proprieta Common AVI e scegliere una delle AVI disponibili 
dall'elenco a discesa; oppure 

• Selezionare la proprieta FileName e fare clic sul pulsante ellissi (...), scegliere un 
file AVI da una directory locale o di rete disponibile e fare clic su Open nella 
finestra di dialogo Open AVI; oppure 

• Selezionare la risorsa di un file AVI attraverso le proprieta ResName o ResID. Per 
indicare il modulo che contiene la risorsa identificata da ResName o ResID, si 
deve usare ResHandle. 

Tale operazione carica il file AVI in memoria. Se si desidera visualizzare il primo 
frame del clip AVI sullo schermo finche non viene riprodotto usando la proprieta 
Active o il metodo Play, impostare la proprieta Open a true. 

4 Impostare la proprieta Repetitions al numero di volte che il clip AVI deve essere 
riprodotto. Se questo valore e 0, la sequenza viene ripetuta finche non viene 
chiamato il metodo Stop. 

5 Apportare tutte le altre modifiche alle impostazioni del controllo di animazione. 
Per esempio, se si desidera cambiare il primo frame visualizzato quando si apre il 
controllo di animazione, impostare la proprieta StartFrame al valore del frame 
desiderate 

6 Impostare la proprieta Active a true usando l'elenco a discesa o scrivere un gestore 
di evento per eseguire il clip AVI quando in fase di esecuzione si verifica uno 
specifico evento. Per esempio, per attivare il clip AVI quando si fa clic su un 
oggetto pulsante, si deve scrivere l'evento OnClick del pulsante che lo specifica. In 
alternativa, per specificare quando deve essere riprodotto l'AVI si puo chiamare il 
metodo Play. 
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Se vengono apportate modifiche alia scheda o ad un qualsiasi suo componente 
dopo aver impostato Active a true, la proprieta Active diventa false ed e necessario 
reimpostarla a true. Questa operazione deve essere effettuata prima di awiare 
l'applicazione o durante la sua esecuzione. 



Esempio di aggiunta di clip video senza suono 

Si supponga di voler visualizzare un logo animato come prima schermata di 
un'applicazione. Terminata la riproduzione del logo, la schermata deve scomparire. 

Per eseguire questo esempio, occorre creare un nuovo progetto e salvare il file 
Unitl.cpp come Frmlogo.cpp e il file Projectl.cpp come Logo.bpr. Quindi: 

1 Fare doppio clic sull'icona del controllo di animazione sulla pagina Win32 della 
Component palette. 

2 Usando l'Object Inspector, impostarne la proprieta Name a Logol. 

3 Selezionare la proprieta FileName, fare clic sul pulsante ellissi (...), scegliere il file 
dillo.avi dalla directory ..\Examples\MFC\General I Cmnctrls. Quindi fare clic su 
Open nella finestra di dialogo Open AVI. 

Questa operazione carica in memoria il file dillo.avi. 

4 Posizionare sulla scheda la casella del controllo di animazione, facendo clic e 
trascinandola nell'angolo superiore destro della scheda. 

5 Impostarne la proprieta Repetitions a 5. 

6 Fare clic sulla scheda per assegnarle il fuoco, e impostarne la proprieta Name a 
LogoForml e la proprieta Caption a Logo Window. A questo punto diminuire 
l'altezza della scheda per centrare a destra il controllo Animate. 

7 Fare doppio clic sull'evento OnActivate della scheda e scrivere il seguente codice 
per eseguire il clip AVI quando la scheda ha il fuoco in fase di esecuzione: 

Logol->Active = true; 

8 Fare doppio clic sull'icona Label nella pagina Standard della Component palette. 
Selezionare la proprieta Caption e immettere Welcome to Armadillo Enterprises 4.0. 
Quindi, selezionare la proprieta Font, fare clic sul pulsante ellissi (...), quindi 
scegliere nella finestra di dialogo Font come Font Style: Bold, Size: 18, Color: Navy 
e fare clic su OK. Fare clic e trascinare il controllo etichetta per centrarlo nella 
scheda. 

9 Fare clic sul controllo di animazione per ridargli il fuoco. Fare doppio clic sul suo 
evento OnStop e scrivere il seguente codice per chiudere la scheda quando il file 
AVI termina l'esecuzione: 

LogoForml->Close() ; 

10 Selezionare Run I Run per eseguire la finestra del logo animato. 
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Aggiunta di clip audio e/o video a un'applicazione 



II componente MediaPlayer di C++Builder consente di aggiungere audio e/o video 
clip all'applicazione. Questo componente apre un dispositivo mediale e riproduce, 
termina, sospende, registra, ecc, i clip audio e/o video usati dal dispositivo mediale. 
Questo puo essere un dispositivo hardware o software. 

Nella programmazione multipiattaforma il supporto per clip audio e video non e 
disponibile. 

Per aggiungere a un'applicazione un clip audio e/o video: 

1 Fare doppio clic sull'icona MediaPlayer nella pagina System della Component 
palette. Questa operazione colloca automaticamente un controllo MediaPlayer 
nella finestra della scheda nella quale si vuole la funzione mediale. 

2 Usando l'Object Inspector, selezionare la proprieta Name e immettere un nuovo 
nome per il controllo MediaPlayer. Questa procedura deve essere eseguita quando 
si chiama il controllo MediaPlayer. (Per dare un nome agli identificatori C++, si 
devono usare le regole standardntifiers.) 

Per impostare in fase di progettazione le proprieta e per creare i gestori di evento, 
si deve lavorare sempre direttamente nell'Object Inspector. 

3 Selezionare la proprieta DeviceType e scegliere il tipo di dispositivo appropriato da 
aprire usando la proprieta AutoOpen o il metodo Open. (Se DeviceType e 
dtAutoSelect, il tipo di dispositivo viene selezionato in base all'estensione del file 
mediale specif icato dalla proprieta FileName.) Per ulteriori informazioni sui tipi di 
dispositivo e sulle loro funzioni, consultare laTabella 10.6. 

4 Se il dispositivo memorizza il suo supporto in un file, specificarne il nome usando 
la proprieta FileName. Selezionare la proprieta FileName, fare clic sul pulsante coi 
puntini di sospensione (...) e scegliere un file mediale da una directory locale o di 
rete disponibile e fare clic su Open nella finestra di dialogo omonima. In 
alternativa, inserire in fase di esecuzione l'hardware (disco, cassetta o altro) in cui 
e memorizzato il supporto per il dispositivo mediale selezionato. 

5 Impostare la proprieta AutoOpen a true. In questo modo il riproduttore mediale 
apre automaticamente il dispositivo specificato quando viene creata in fase di 
esecuzione la scheda che contiene il controllo MediaPlayer.Se AutoOpen e false, il 
dispositivo deve essere aperto con una chiamata al metodo Open. 

6 Impostare la proprieta AutoEnable a true per attivare o disattivare 
automaticamente i pulsanti MediaPlayer, come richiesto in fase di esecuzione; 
oppure, fare doppio clic sulla proprieta EnabledButtons per impostare ciascun 
pulsante a true o false, a seconda di quali si desidera attivare o disattivare. 

II dispositivo multimediale viene riprodotto, messo in pausa, fermato, e cosi via, 
quando l'utente fa clic sul pulsante corrispondente sul componente Mediaplayer. 
II dispositivo puo essere controllato anche tramite i metodi che corrispondono ai 
pulsanti (Play, Pause, Stop, Next, Previous, e cosi via). 
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7 Posizionare la barra del controllo MediaPlayer sulla scheda facendo clic e 
trascinandola nel posto desiderato sulla scheda o selezionando la proprieta Align e 
scegliendo la posizione di allineamento corretta dall'elenco a discesa. 

Se si vuole che il MediaPlayer sia invisibile in fase di esecuzione, impostare la 
proprieta Visible a false e controllare il dispositivo chiamando i metodi appropriati 

(Play, Pause, Stop, Next, Previous, Step, Back, Start Recording, Eject). 

8 Apportare tutte le altre modifiche alle impostazioni del controllo MediaPlayer. Per 
esempio, se il supporto richiede una finestra di visualizzazione, impostare la 
proprieta Display al controllo che visualizza il supporto. Se il dispositivo usa piu 
tracce, impostare la proprieta Tracks alia traccia desiderata. 



Tabella 10.6 Tipi di dispositivi multimediali e loro funzioni 



Tipo di 
dispositivo 

dtAVIVideo 
dtCDAudio 

dtDAT 

dtDigitalVideo 

dtMMMovie 

dtOverlay 

dtScanner 

dtSequencer 
dtVCR 

dtWaveAudio 



Software/Hardware usato Esegue 

AVI Video Player for 
Windows 

CD Audio Player for 
Windows or a CD Audio 
Player 

Digital Audio Tape Player 

Digital Video Player for 
Windows 

MM Movie Player 

Overlay device 

Image Scanner 



Usa le 
tracce 



Usa una 
finestra di 
visualizzazione 



File Video AVI No Si 



CD Audio Si No 



MIDI Sequencer for 
Windows 

Video Cassette Recorder 

Wave Audio Player for 
Windows 



Nastri audio digitali Si No 

FileAVXMPG, No Si 
MOV 

Film MM No Si 

Video analogici No Si 

N/DperP/ay No No 
(Record fa scorrere 
le immagini) 

MIDI files Si No 

Videocassette No Si 

File WAV No No 



Esempio di aggiunta di clip audio e/o video (solo VCL) 

Questo esempio esegue un video clip AVI di un'inserzione multimediale per 
C++Builder. Per eseguire questo esempio, occorre creare un nuovo progetto e salvare 
il file Unitl.cpp in FrmAd.cpp e il file Projectl.bpr in MmediaAd.bpr. Quindi: 

1 Fare doppio clic sull'icona MediaPlayer nella pagina System della Component 
palette. 

2 Usando l'Object Inspector, impostare la proprieta Name del MediaPlayer a 
VideoPlayerl. 

3 Selezionare la sua proprieta DeviceType e scegliere dtAVIVideo dall'elenco a 
discesa. 
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4 Selezionare la proprieta FileName, fare clic sul pulsante coi puntini di sospensione 
(. . .), scegliere il file dalla directory .A Examples \Coolstuf. directory. Fare clic su 
Open nella finestra di dialogo omonima. 

5 Impostare la proprieta AutoOpen a true e la proprieta Visible a false. 

6 Fare doppio clic sull'icona Animate dalla pagina Win32 della Component palette. 
Impostarne la proprieta AutoSize a false, la proprieta Height a 275 e la proprieta 
Width a 200. Fare clic e trascinare il controllo di animazione nell'angolo superiore 
sinistro della scheda. 

7 Fare clic sul MediaPlayer per ridargli il fuoco. Selezionare la sua proprieta Display 
e scegliere Animatel dall'elenco a discesa. 

8 Fare clic sulla scheda per darle il fuoco e selezionare la sua proprieta Name e 
immettere C++_Ad. A questo punto, riportare la scheda alle dimensioni del 
controllo di animazione. 

9 Fare doppio clic sull'evento OnActivate della scheda e scrivere il seguente codice 
per eseguire il video AVI quando la scheda ha il fuoco: 

VideoPlayerl->Play() ; 

10 Scegliere Run I Run per eseguire il video AVI. 
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Scrittura di applicazioni multi-thread 

C++Builder fornisce diversi oggetti che semplificano la scrittura di applicazioni 
multi-thread. Queste sono applicazioni che includono diversi percorsi simultanei di 
esecuzione. Poiche l'uso di piu thread comporta una certa complessita, e possibile 
migliorare i programmi: 

• Evitando i colli di bottiglia. Con un solo thread un programma deve bloccare 
completamente l'esecuzione quando aspetta che terminino processi lenti come 
l'accesso ai file sul disco, la comunicazione con altre macchine o la visualizzazione 
di un contenuto multimediale. La CPU rimane in stato di attesa finche il processo 
non viene completato. Con piu thread l'applicazione pud proseguire l'esecuzione 
in thread diversi mentre un thread aspetta i risultati di un processo lento. 

• Organizzando il comportamento del programma. Spesso il comportamento di un 
programma pud essere organizzato in piu processi paralleli che funzionano in 
modo indipendente. Usare i thread per lanciare una singola sezione di codice 
contemporaneamente per ciascuno di questi casi paralleli. Usare i thread per 
assegnare la priorita alle varie operazioni del programma in modo che la CPU 
possa avere piu tempo a disposizione per le operazioni piu importanti. 

• Con l'elaborazione multiprocesso. Se il sistema che esegue il programma ha piu 
processori, e possibile migliorare le prestazioni dividendo il lavoro in diversi 
thread e permettendo l'esecuzione simultanea su processori distinti. 

Non tutti i sistemi operativi implementano una vera elaborazione multiprocesso, 
anche nel caso sia supportata dall'hardware utilizzato. Ad esempio, Windows 9x 
Simula solamente l'elaborazione multiprocesso, anche se l'hardware utilizzato lo 
consentirebbe. 

Definizione di oggetti thread 



Per la maggior parte delle applicazioni e possibile usare un oggetto thread per 
rappresentare un thread di esecuzione di un'applicazione. Gli oggetti thread 
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semplificano la scrittura di applicazioni multi-thread incapsulando i thread che e 
necessario usare piu frequentemente. 

Gli oggetti thread non consentono di controllare gli attributi di sicurezza o le 
dimensioni dello stack dei thread. Qualora questo controllo sia necessario, occorre 
usare le funzioni CreateThread o BeginThread delle API di Windows. Anche quando si 
usano le Windows Thread API calls o BeginThread, e sempre possibile sfruttare i 
vantaggi di alcuni degli oggetti thread di sincronizzazione e dei metodi descritti nella 
sezione "Coordinamento dei thread" a pagina 11-7. Per maggiori informazioni 
sull'utilizzo di CreateThread o BeginThread, consultare la Guida in linea di Windows. 

Per usare un oggetto thread in un'applicazione, e necessario creare un nuovo 
discendente di TThread. A questo scopo, scegliere File I New dal menu principale. 
Nella finestra di dialogo New Items, fare doppio clic su Thread-Object (oppure su 
Thread Object di CLX per applicazioni multipiattaforma) e immettere un nome di 
classe, come TMyThread. Per assegnare un nome a questo nuovo thread, selezionare 
la casella di controllo Named Thread e immettere un nome per il thread (solo per 
VCL). L'assegnazione di un nome al thread semplifica il tracciamento del thread 
durante il debug. Una volta fatto clic su OK, C++Builder crea un nuovo file .cpp e un 
file header per implementare il thread. Per ulteriori informazioni sull'assegnazione 
di un nome per il thread, si veda il paragrafo "Assegnazione di un nome al thread" a 
pagina 11-13. 

A differenza della maggior parte delle finestre di dialogo nell'IDE che richiedono un 
nome di classe, la finestra di dialogo New Thread Object non mette automaticamente 
una "F come prefisso del nome di classe fornito. 

II file .cpp generato automaticamente contiene lo schema di codice per il nuovo 
oggetto thread. Un thread al quale e stato attribuito come nome TMyThread apparira 
piu o meno in questo modo: 

// 

♦include <vcl.h> 
tpragma hdrstop 

((include "Unit2.h" 
ipragma package (smart_mit) 

// 

__fastcall TMyThread: : TMyThread (bool CreateSuspended) : TThread (CreateSuspended) 
{ 
} 

// 

void __fastcall TMyThread: : Executed 
{ 

// Place thread code here 

} 

// 

Occorre completare il codice per il costruttore e per il metodo Execute. Le fasi relative 
a tale operazione vengono descritte nelle sezioni successive. 



11-2 Guida alia programmazione 



Inizializzazione del thread 



Definizione d i oggetti thread 



Utilizzare il costruttore per inizializzare una nuova classe thread. E qui che si puo 
assegnare una priorita predefinita per il thread e indicare se verra rilasciato 
automaticamente al termine dell'esecuzione. 

Assegnazione di una priorita predefinita 

La priorita indica il grado di attenzione che il thread riceve quando il sistema 
operativo programma il tempo che la CPU deve dedicare ad ogni thread 
dell'applicazione. Per gestire operazioni per le quali il tempo e determinante, si deve 
usare un thread ad alta priorita, mentre per tutte le altre operazioni si puo ricorrere 
ad un thread a bassa priorita. Per indicare la priorita dell'oggetto thread, impostare la 
proprieta Priority. 

Se si sta scrivendo un'applicazione Windows, i valori di Priority sono disposti su una 
scala, come descritto nella Tabella 11.1: 

Tabella 11.1 Priorita del thread 



Valori 


Priorita 


tpldle 


11 thread viene eseguito solo quando il sistema e inattivo. Windows non 




interrompera gli altri thread per eseguirne uno con priorita tpldle. 


tpLowest 


La priorita del thread e due punti sotto il normale. 


tpLower 


La priorita del thread e un punto sotto il normale. 


tpNormal 


11 thread ha priorita normale. 


tp Higher 


La priorita del thread e un punto sopra il normale. 


tp Highest 


La priorita del thread e due punti sopra il normale. 


tpTimeCritical 


11 thread riceve la priorita piu alta. 



Se si scrive un'applicazione multipiattaforma, e necessario utilizzare codice 
differente per l'assegnazione delle priorita in Windows e Linux. In Linux, Priority e 
un valore numerico che dipende dalle politiche di threading che puossono essere 
cambiate solo dall'utente root. Per i dettagli, consultare la versione CLX di TThread e 
Priority nella Guida in linea. 

L'aumento della priorita del thread di un'operazione che richiede un uso intensivo 
della CPU puo lasciare "a bocca asciutta" gli altri thread dell'applicazione. Esso si 
applica solo ai thread che trascorrono la maggior parte del tempo in attesa di eventi 
esterni. 

II codice seguente mostra il costruttore di un thread a bassa priorita che esegue 
operazioni secondarie che non interferiranno con le altre prestazioni 
dell'applicazione: 

// 

__fastcall TMyThread: : TMyThread (bool CreateSuspended) : TThread (CreateSuspended) 
{ 

Priority = tpldle; 

} 

// 
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Come indicare quando i thread vengono rilasciati 

Quando i thread terminano le rispettive operazioni, di solito vengono semplicemente 
rilasciati. In questo caso, e piu facile permettere all'oggetto thread di rilasciarsi da 
solo. Per fare cio, impostare la proprieta FreeOnTerminate a true. 

A volte, tuttavia, il termine di un thread deve essere coordinato con altri thread. Ad 
esempio, potrebbe essere necessario aspettare il valore restituito da un thread prima 
di eseguire un'azione in un altro thread. In questo caso, non si potra rilasciare il 
primo thread finche il secondo non ha ricevuto il valore restituito. Questa situazione 
puo essere gestita impostando FreeOnTerminate a false e quindi rilasciare il primo 
thread in modo esplicito dall'interno del secondo. 

Scrittura della funzione thread 



II metodo Execute e una funzione thread. Puo essere considerato come un programma 
che viene lanciato dall'applicazione, con la differenza che condivide lo stesso spazio 
di elaborazione. La scrittura della funzione thread e un po' piu difficile della scrittura 
di un programma distinto perche richiede la verifica del fatto che non venga 
sovrascritta la memoria usata dagli altri thread dell'applicazione. D'altra parte, dal 
momento che il singolo thread condivide lo stesso spazio di elaborazione con gli altri 
thread, e possibile usare la memoria condivisa per la comunicazione tra i thread. 

Utilizzo del thread VCL/CLX principale 

Quando si usano oggetti della gerarchia di oggetti della VCL o di CLX, non si ha 
alcuna garanzia sul fatto che le loro proprieta e i loro metodi salvaguardino i thread. 
Ossia, l'accesso alle proprieta o l'esecuzione dei metodi possono eseguire operazioni 
che usano memoria non protetta dalle operazioni degli altri thread. Tenuto conto di 
cio, si imposta un thread principale per l'accesso agli oggetti della VCL e di CLX. 
Questo e il thread che gestisce tutti i messaggi di Windows ricevuti dai componenti 
dell'applicazione. 

Se tutti gli oggetti accedono alle loro proprieta ed eseguono i loro metodi all'interno 
di questo singolo thread, non occorre preoccuparsi del fatto che interferiscano tra 
loro. Per usare il thread principale, creare una routine distinta che esegua le 
operazioni desiderate. Richiamarla quindi dall'interno del metodo Synchronize del 
thread. Per esempio: 

void __fastcall TMyThread: :PushTheButton(void) 

{ 

Buttonl->Click() ; 

} 

void __fastcall TMyThread: : Execute ( ) 
{ 

Synchronize) (TThreadMethod) PushTheButton) ; 

} 
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Synchronize aspetta il thread principale per avviare il ciclo di messaggi, dopo di che 
esegue il metodo passato. 

Dal momento che Synchronize usa il ciclo di messaggi, non funziona nelle 
applicazioni console. Per proteggere l'accesso agli oggetti VCL e CLX nelle 
applicazioni per console, si devono, pertanto, usare altri meccanismi, come le sezioni 
critiche. 

Non occorre usare sempre il thread principale. Alcuni oggetti sono associati ai 
thread. Omettendo l'uso del metodo Synchronize quando si e certi che i metodi di un 
oggetto sono thread-safe si miglioreranno le prestazioni, poiche non occorrera 
aspettare che il thread VCL o CLX avvii il proprio ciclo di messaggi. Non e necessario 
usare il metodo Synchronize nelle seguenti situazioni: 

• I componenti per l'accesso ai dati sono thread-safe a patto che, per i dataset che 
utilizzano BDE, ciascun thread abbia il proprio componente session di database. 
L'unica eccezione si presenta quando si utilizzano i driver di Access Microsoft, che 
sono costruiti usando una libreria Microsoft, che non e thread-safe. Per dbDirect, 
finche la libreria client del produttore e thread-safe, i componenti dbDirect 
saranno thread-safe. I componenti ADO e InterbaseExpress sono thread-safe. 

Quando si usano componenti di accesso ai dati, occorre sempre passare al metodo 
Synchronize tutte le chiamate che interessano i controlli associati ai dati. Quindi, 
per esempio, occorre sincronizzare le chiamate che collegano un controllo dati ad 
un dataset impostando la proprieta DataSet dell'oggetto data source, ma non 
occorre alcuna sincronizzazione per accedere ai dati di un campo del dataset. 

Per maggiori informazioni sull'utilizzo delle sessioni database con i thread, in 
applicazioni che utilizzano BDE, consultare "Gestione di sessioni multiple" a 
pagina 24-29. 

• Gli oggetti DataCLX sono thread-safe mentre gli oggetti VisualCLX non lo sono. 

• Gli oggetti grafici sono thread-safe. Non occorre usare il thread VCL principale 
per accedere a TFont, TPen, TBrush, TBitmap, TMetafile (solo VCL), TDrawing(solo 
CLX), o TIcon. Gli oggetti canvas possono essere utilizzati all'estemo del metodo 
Synchronize bloccandoli (vedere "Blocco di oggetti" a pagina 11-8). 

• Benche gli oggetti list non siano thread-safe, si pud usare una versione thread-safe, 
TThreadList, al posto di TList. 

Chiamare periodicamente la routine CheckSynchronize dall'interno del thread 
principale dell'applicazione in modo che i thread in background possano 
sincronizzare la propria esecuzione con il thread principale. II momento ideale per 
chiamare CheckSynchronize e quando l'applicazione e inattiva (ad esempio, da un 
gestore di evento Onldle ). Cio garantisce che e sicuro effettuare chiamate ai metodi 
nel thread di background. 

Uso di variabili locali al thread 

II metodo Execute e tutte le routine che chiama hanno proprie variabili locali, 
esattamente come qualsiasi altra routine di C++. Queste routine possono accedere 
anche a tutte le variabili globali. Infatti, queste variabili forniscono un potente 
meccanismo per la comunicazione tra i thread. 
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Qualche volta, tuttavia, puo risultare preferibile usare variabili che sono globali per 
tutte le routine che vengono eseguite nel thread, ma non sono condivise con altre 
istanze della stessa classe thread. Per ottenere questo risultato, occorre dichiarare le 
variabili locali al thread. Creare una variabile locale al thread aggiungendo alia 
dichiarazione della variabile il modificatore thread. Ad esempio: 

int thread x; 

dichiara una variabile di tipo integer che e privata per ciascun thread 
dell'applicazione, ma globale all'intemo di ciascun thread. 

II modificatore thread puo essere utilizzato solamente per variabili globali (il cui 

campo d'azione e il file) e statiche. Pointer e Function non possono essere variabili 
thread. Non funzionano come variabili neppure i tipi che usano la semantica a sola 
scrittura, cosi come pure le variabili di tipo AnsiStrings. Un elemento di programma 
che richieda una inizializzazione o una finalizzazione al momento dell'esecuzione 
non puo essere dichiarato di tipo thread. 

Le seguenti dichiarazioni richiedono una inizializzazione al momento 
dell'esecuzione e pertanto non sono consentite. 

int f( ); 

int __thread x = f( ); // illegal 

La creazione di un'istanza di una classe mediante un costruttore o un distruttore 
definito dall'utente richiede una inizializzazione al momento dell'esecuzione e non e, 
pertanto, consentita: 

class X { 

X( ); 
~X( ); 

}; 

X __thread myclass; // illegal 

Controllo del termine da parte di altri thread 

II thread inizia l'esecuzione quando viene chiamato il metodo Execute (vedere 
"Esecuzione di oggetti thread" a pagina 11-12) e continua finche Execute non finisce. 
Cio riflette il modello che prevede che il thread esegua una specifica operazione e 
quindi si fermi non appena ha terminato. Qualche volta, tuttavia, un'applicazione ha 
bisogno di un thread da eseguire finche non viene soddisfatto un criterio esterno. 

Controllando la proprieta Terminated, si puo consentire ad altri thread di segnalare al 
thread attivo che e il momento di terminare l'esecuzione. Quando un altro thread 
tenta di interrompere il thread attivo, chiama il metodo Terminate. Terminate imposta 
la proprieta Terminated del thread attivo a true. Spetta al metodo Execute 
implementare il metodo Terminate controllando e rispondendo alia proprieta 
Terminated. II seguente esempio mostra un modo per eseguire questa operazione: 

void __fastcall TMyThread: : Executed 
{ 

while (! Terminated) 
PerformSomeTask( ) ; 

} 
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Gestione delle eccezioni nella funzione di thread 

II metodo Execute deve intercettare tutte le eccezioni che si verificano nel thread. Se 
non si riesce a intercettare un'eccezione nella funzione di thread, l'applicazione 
potrebbe provocare violazioni di accesso. Cio potrebbe non essere evidente quando si 
sta sviluppando l'applicazione, in quanta 1'IDE intercetta le eccezioni, ma quando si 
eseguira l'applicazione esternamente al debugger, l'eccezione causera un errore di 
esecuzione e l'applicazione si blocchera. 

Per intercettare le eccezioni che si verificano all'interno della funzione di thread, 
aggiungere un blocco try.. .catch all'implementazione del metodo Execute: 

void __fastcall TMyThread: : Executed 
{ 

try 

{ 

while (! Terminated) 
PerformSomeTask( ) ; 

} 

catch (...) 

{ 

// do something with exceptions 

} 

} 

Scrittura del codice di pulizia 



E possibile centralizzare il codice di pulizia quando il thread termina l'esecuzione. 
Appena prima che un thread cessi l'esecuzione, si verifica un evento OnTerminate. 
Per garantire che venga sempre eseguito, indipendentemente dal percorso di 
esecuzione seguito dal metodo Execute, bisogna collocare il codice di pulizia nel 
gestore di eventi OnTerminate. 

II gestore di eventi OnTerminate non viene eseguito come parte del thread. Viene 
invece eseguito nel contesto del thread VCL o CLX principale dell'applicazione. Cio 
comporta due implicazioni: 

• Non e possibile usare nessuna delle variabili locali al thread in un gestore di eventi 
OnTerminate (a meno che non si vogliano i valori del thread VCL o CLX 
principale). 

• Si pud accedere con tranquillita a tutti i componenti e agli oggetti VCL o CLX dal 
gestore di eventi OnTerminate senza preoccuparsi dell'eventuale conflitto con altri 
thread. 

Per maggiori informazioni sul thread principale di VCL o di CLX, vedere "Utilizzo 
del thread VCL/ CLX principale" a pagina 11-4. 

Coordinamento dei thread 



Quando si scrive del codice da eseguire quando viene attivato il thread, bisogna 
considerare il comportamento degli altri thread che possono essere eseguiti 
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contemporaneamente. In particolare, si deve prestare molta attenzione ad evitare che 
due thread cerchino di usare lo stesso oggetto o la stessa variabile globale nello stesso 
istante. Inoltre, il codice di un thread puo dipendere dai risultati di operazioni 
eseguite da altri thread. 

Come evitare I'accesso simultaneo 



Per evitare conflitti con altri thread quando si accede agli oggetti o alle variabili 
globali, puo risultare necessario bloccare l'esecuzione degli altri thread finche il 
codice del thread non ha terminato un'operazione. Si deve fare attenzione a non 
bloccare l'esecuzione di altri thread senza che ce ne sia la necessita. Cio potrebbe 
provocare un serio degrado delle prestazioni e annullare quasi tutti i vantaggi 
derivanti dall'uso di piu thread. 

Blocco di oggetti 

Alcuni oggetti hanno un blocco integrato che impedisce l'esecuzione di altri thread 
per l'uso dell'istanza di quell'oggetto. 

Per esempio, gli oggetti canvas (TCanvas e discendenti) hanno un metodo Lock che 
impedisce agli altri thread di accedere al canvas finche non viene chiamato il metodo 
Unlock. 

Anche la VCL e la CLX includono un oggetto list thread-safe, TThreadList. 
Chiamando TThreadList::LockList viene restituito l'oggetto list e viene anche impedito 
ad altri thread in esecuzione di usare la lista finche non viene chiamato il metodo 
UnlockList. Le chiamate a TCanvas::Lock o a TThreadList::LockList possono essere 
annidate tranquillamente. II blocco non viene rilasciato finche non si verifica una 
corrispondenza tra l'ultima chiamata di blocco ed una chiamata di sblocco nello 
stesso thread. 

Uso di sezioni critiche 

Se gli oggetti non forniscono un blocco integrato, si puo usare una sezione critica. 
Queste sezioni funzionano come cancelli che consentono l'ingresso di un solo thread 
per volta. Per usare una sezione critica, creare un'istanza globale di TCriticalSection. 
TCriticalSection ha due metodi, Acquire (che impedisce agli altri thread di eseguire la 
sezione) e Release (che rimuove il blocco). 

Ciascuna sezione critica e associata alia memoria globale che si intende proteggere. 
Ogni thread che accede a quella memoria globale deve usare prima il metodo Acquire 
per verificare che nessun altro thread la stia usando. Alia fine, i thread chiamano il 
metodo Release in modo che altri thread possano accedere alia memoria globale 
chiamando Acquire. 

Le sezioni critiche funzionano solo se ogni thread le usa per accedere alia memoria 
globale associata. I thread che ignorano la sezione critica e accedono alia memoria 
globale senza chiamare Acquire possono provocare problemi di accesso simultaneo. 

Per esempio, si consideri un'applicazione che ha una variabile globale della sezione 
critica, pLockXY, che blocca I'accesso alle variabili globali X e Y. Qualsiasi thread che 
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usa X o Y deve evitare di utilizzarla con chiamate alia sezione critica come 
nell'esempio seguente: 

pLockXY->Acquire() ; // lock out other threads 
try 

{ 

Y = sin(X) ; 

} 

finally 

{ 

pLockXY->Release() ; 

} 

Uso del sincronizzatore multilettura a scrittura esclusiva 

Quando si usano sezioni critiche per proteggere la memoria globale, solo un thread 
per volta puo usare la memoria. Cio puo creare un livello di protezione superiore a 
quello richiesto, specialmente se si ha a che fare con un oggetto o una variabile che 
devono essere letti spesso ma su cui si scrive molto raramente. Non si corre alcun 
rischio se diversi thread leggono contemporaneamente la stessa memoria, finche 
nessun thread cerca di scrivervi sopra. 

Quando si ha a che fare con della memoria globale che viene letta spesso, ma nella 
quale i thread scrivono raramente, si puo proteggerla usando 

TMultiReadExclusiveWriteSynchronizer. Questo oggetto si comporta come una sezione 
critica, che consente pero a diversi thread di leggere la memoria che protegge, 
sempre che non vi sia un altro thread che vi sta scrivendo. I thread devono avere 
accesso esclusivo per la scrittura nella memoria protetta tramite 

TMultiReadExclusiveWriteSynchronizer. 

Per usare un sincronizzatore multilettura a scrittura esclusiva, occorre creare 
un'istanza globale di TMultiReadExclusiveWriteSynchronizer che viene associata alia 
memoria globale che si intende proteggere. Ogni thread che legge da questa memoria 
chiama prima il metodo BeginRead. BeginRead garantisce che nessun altro thread stia 
al momento scrivendo nella memoria. Quando un thread termina la lettura della 
memoria protetta, chiama il metodo EndRead. Tutti i thread che scrivono nella 
memoria protetta devono chiamare prima BeginWrite. BeginWrite garantisce che 
nessun altro thread stia al momento leggendo o scrivendo nella memoria. Quando un 
thread finisce di scrivere nella memoria protetta, chiama il metodo EndWrite, in 
modo che i thread che sono in attesa di leggere la memoria possano iniziare. 

Come le sezioni critiche, il sincronizzatore multilettura a scrittura esclusiva funziona 
solo se viene utilizzato da tutti i thread per accedere alia memoria globale associata.I 
thread che ignorano il sincronizzatore ed accedono alia memoria globale senza 
chiamare BeginRead o BeginWrite creano problemi di accesso simultaneo. 

Altre tecniche per la condivisione della memoria 

Quando si utilizzano oggetti della gerarchia della VCL o CLX, per eseguire il codice 
si deve ricorrere al thread principale. L'uso di questo thread assicura che l'oggetto 
non acceda indirettamente alia memoria che viene usata anche dagli oggetti VCL o 
CLX in altri thread. L'utilizzo di questo thread assicura che l'oggetto non acceda 
indirettamente alia memoria che viene usata anche dagli oggetti di VCL e di CLX in 
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altri thread. Per maggiori informazioni sul thread principale, vedere "Utilizzo del 
thread VCL/ CLX principale" a pagina 11-4. 

Se la memoria globale non ha bisogno di essere condivisa tra piu thread, bisogna 
considerare la possibility di usare variabili locali al thread al posto delle variabili 
globali. Usando variabili locali al thread, il thread non ha bisogno di aspettare o di 
sbloccare un altro thread. Per maggiori informazioni sulle variabili locali al thread, 
vedere "Uso di variabili locali al thread" a pagina 11-5. 

Attesa di altri thread 



Se il thread utilizzato deve attenderne un altro per finire una certa operazione, e 
possibile comunicargli di sospendere temporaneamente l'esecuzione. Si pud 
aspettare che un altro thread termini completamente l'esecuzione oppure che segnali 
che ha completato un'operazione. 

Attesa che un thread termini l'esecuzione 

Per aspettare che un altro thread finisca l'esecuzione, usare il metodo WaitFor 
dell'altro thread. WaitFor non restituisce il controllo finche l'altro thread non 
interrompe l'esecuzione, completando il suo metodo Executeo terminando a causa di 
un'eccezione. Per esempio, il codice seguente aspetta finche un altro thread non 
riempie un oggetto list del thread, prima di accedere agli oggetti della lista: 

if (pListFillingThread->WaitFor ( ) ) 
{ 

TList *pList = ThreadListl->LockList() ; 
for (int i = 0; i < pList->Count ; i++) 

ProcessItem(pList->Items [i] ) ; 
ThreadListl->UnlockList ( ) ; 

} 

Nell'esempio precedente gli elementi della lista erano accessibili solo quando il 
metodo WaitFor indicava che la lista era stato effettivamente riempita. Questo valore 
restituito deve essere assegnato dal metodo Execute del thread che era atteso. 
Tuttavia, poiche i thread che chiamano WaitFor vogliono conoscere il risultato 
dell'esecuzione del thread e non il codice che chiama Execute, il metodo Execute non 
restituisce alcun valore. Invece, il metodo Execute imposta la proprieta ReturnValue. 
ReturnValue viene quindi restituito dal metodo WaitForquando viene chiamato da 
altri thread. I valori restituiti sono interi. L'applicazione determina il loro significato. 

Attesa che venga completata un'operazione 

Qualche volta e necessario aspettare che un thread finisca una certa operazione 
piuttosto che attendere che uno specifico thread termini l'esecuzione. Per ottenere 
questo risultato, occorre usare un oggetto evento. Gli oggetti evento (TEvent) devono 
essere creati con un campo d'azione globale in modo che possano agire come segnali 
visibili per tutti i thread. 

Quando un thread completa un'operazione da cui dipendono altri thread, chiama 
TEventr.SetEvent. SetEvent attiva il segnale, in modo che tutti gli altri thread che 
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controllano sapranno che l'operazione e stata completata. Per disattivare il segnale, 
usare il metodo ResetEvent. 

Per esempio, si consideri una situazione in cui si deve aspettare che terminino 
l'esecuzione diversi thread anziche uno solo. Dal momento che non si sa quale thread 
finira per ultimo, non basta usare il metodo WaitFor di uno dei thread. Occorre, 
invece, che ogni thread incrementi un contatore quando ha finito, e che l'ultimo 
thread segnali la fine dell'intera operazione attivando un evento. Instead, you can 
have each thread increment a counter when it is finished, and have the last thread 
signal that they are all done by setting an event. 

II codice seguente mostra la fine del gestore di evento OnTerminate per tutti i thread 
che devono completare l'esecuzione. CounterGuard e un oggetto sezione critica 
globale, che impedisce che piu thread utilizzino il contatore contemporaneamente. 
Counter e una variabile globale che conta il numero di thread che sono stati 
completati. 

void fastcall TDataModule: :TaskThreadTerminate(TObject *Sender) 

{ 

CounterGuard->Acquire() ; // lock the counter 

if (--Counter == 0) // decrement the global counter 

Eventl->SetEvent ( ) ; // signal if this is the last thread 
CounterGuard->Release() ; // release the lock on the counter 

} 

II thread principale inizializza la variabile Counter, avvia l'esecuzione dei thread e 
aspetta il segnale che indica che tutti hanno terminato chiamando il metodo WaitFor. 
WaitFor attende per un tempo specificato il segnale da impostare, e restituisce uno 
dei valori elencati nella Tabella 11.2. 

Tabella 11.2 Valori di ritorno di Waifor 



Valori 


Significato 


wrSignaled 


11 segnale dell'evento e stato impostato. 


wrTimeout 


11 tempo specificato e trascorso senza che il segnale sia stato impostato. 


wrAbandoned 


L'oggetto evento e stato distrutto prima che sia trascorso il periodo di time out. 


wrError 


Si e verificato un errore durante l'attesa. 



II codice seguente mostra come il thread principale awia l'esecuzione dei thread, 
quindi ricomincia quando tutti hanno terminato l'operazione: 

Eventl->ResetEvent ( ) ; // clear the event before launching the threads 
for (int i = 0; i < Counter; i++) 

new TaskThread (false ) ; // create and launch task threads 
if (Eventl->WaitFor(20000) != wrSignaled) 

throw Exception; 

// now continue with the main thread, all task threads have finished 

Se non si vuole fermare l'attesa di un evento dopo un determinato periodo di tempo, 
passare il metodo WaitFor con INFINITE come valore del parametro. Bisogna 
prestare attenzione quando si usa INFINITE, perche il thread si blocca se il segnale 
anticipato non viene mai ricevuto. 
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Esecuzione di oggetti thread 



Dopo aver implementato una classe thread fornendole un metodo Execute, e possibile 
usarla nell'applicazione per lanciare il codice nel metodo Execute. Per usare un 
thread, creare innanzi tutto un'istanza della classe thread. Si pud creare un'istanza 
del thread che avvia immediatamente l'esecuzione o il thread stesso in uno stato di 
sospensione, in modo che parta solo quando viene chiamato il metodo Resume. Per 
creare un thread che si awia immediatamente, impostare il parametro 
CreateSuspended del costruttore a false. Per esempio, la seguente riga crea un thread e 
ne avvia l'esecuzione: 

TMyThread *SecondThread = new TMyThread ( false ) ; // create and run the thread 

Bisogna evitare di creare troppi thread nell'applicazione. Le difficolta di gestione di 
piu thread possono influire negativamente sulle prestazioni. II limite consigliato e di 
16 thread per processo su sistemi monoprocessore. Questo limite presuppone che la 
maggior parte di quei thread sia in attesa di eventi esterni. Se i thread sono tutti 
attivi, se ne potranno usare di meno. 

E possibile creare istanze multiple dello stesso tipo di thread per eseguire codice 
parallelo. Per esempio, si pud lanciare una nuova istanza di un thread in risposta ad 
una certa operazione dell'utente, consentendo a ciascun thread l'esecuzione della 
risposta attesa. 

Ridefinizione della priorita predefinita 



Quando la quantita di tempo che la CPU deve dedicare al thread e implicita 
nell'operazione del thread, la sua priorita viene impostata nel costruttore. Cio viene 
descritto nel paragrafo "Inizializzazione del thread" a pagina 11-3. Tuttavia, se la 
priorita del thread varia a seconda di quando esso viene eseguito, creare il thread in 
uno stato di sospensione, impostare la priorita e quindi avviare l'esecuzione del 
thread: 

TMyThread *SecondThread = new TMyThread (true ) ; // create but don't run 
SecondThread->Priority = tpLower; // set the priority lower than normal 
SecondThread->Resume ( ) ; // now run the thread 

Se si scrive un'applicazione multipiattaforma, e necessario utilizzare codice 
differente per l'assegnazione delle priorita in Windows e Linux. In Linux, Priority e 
un valore numerico che dipende dalle politiche di threading che puossono essere 
cambiate solo dall'utente root. Per i dettagli, consultare la versione CLX di TThread e 
Priority nella Guida in linea. 

Awio e interruzione dei thread 



Un thread puo essere avviato ed interrotto un qualsiasi numero di volte prima che 
finisca l'esecuzione. Per interrompere temporaneamente un thread, chiamare il suo 
metodo Suspend. Quando non ci sono problemi nel riprendere l'esecuzione del 
thread, chiamare il suo metodo Resume. Suspend incrementa un contatore interno, in 
modo da poter annidare le chiamate a Suspend e Resume. II thread non riprende 
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l'esecuzione finche tutte le sospensioni non sono state soddisfatte da una chiamata a 

Resume. 

E possibile richiedere che un thread termini anzitempo l'esecuzione chiamando il 
metodo Terminate. Terminate imposta la proprieta Terminated del thread a true.Se il 
metodo Execute e stato implementato correttamente, controlla periodicamente la 
proprieta Terminated, e interrompe l'esecuzione quando Terminated e true. 

Debug di applicazioni multi-thread 



Quando si ef fettua il debug delle applicazioni multi-thread, il tentativo di registrare 
lo stato di tutti i thread che sono eseguiti simultaneamente, o anche di determinare 
quale thread e in esecuzione quando ci si ferma ad un breakpoint, puo generare 
confusione. Per seguire e intervenire su tutti i thread dell'applicazione, si puo usare 
la casella TThread Status. Per visualizzare la casella Thread Status, scegliere dal 
menu principale il comando View I Thread. 

Quando si verifica un evento di debug (breakpoint, eccezione, pausa), la vista dello 
stato dei thread indica in dettaglio la situazione. Fare clic con il tasto destro del 
mouse sulla finestra Thread Status per accedere ai comandi che individuano la 
posizione corrispondente del sorgente o che rendono attivo un thread differente. 
Quando un thread viene contrassegnato come attivo, il passo o la successiva 
operazione da eseguire si riferisce a quel thread. 

La finestra Thread Status elenca tutti i thread di esecuzione dell'applicazione in base 
al rispettivo ID. Se si usano degli oggetti thread, il loro ID e il valore della proprieta 
ThreadlD. Se non si usano oggetti thread, 1TD di ciascun thread viene restituito 
tramite la chiamata a CreateThread o BeginThread. 

Per ulteriori informazioni sulla finestra Thread Status, consultare la Guida in linea. 

Assegnazione di un nome al thread 



Dal momento che risulta difficile correlare un ID di thread con uno dei thread 
presenti nella finestra Thread Status, e possibile assegnare dei nomi alle classi thread. 
Quando si crea una classe thread nella finestra di dialogo Thread Object, oltre a 
immettere un nome di classe, selezionare anche la casella di controllo Named Thread, 
immettere un nome di thread e fare clic su OK. 

L'assegnazione del nome alia classe thread aggiunge un metodo alia classe thread di 
nome SetName. Quando il thread inizia la sua esecuzione, per prima cosa chiama il 
metodo SetName. 

E possibile assegnare un nome ai threads solo nelle applicazioni VCL. 

Conversione di un thread senza nome in uno con nome 

E possibile convertire un thread senza nome in uno con nome. Ad esempio, se si ha 
una classe thread creata con C++Builder 5 o con versioni precedenti, e possibile 
convertirla in un thread con nome seguendo questa procedura. 
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1 Aggiungere alia classe thread il metodo SetName: 

II 

void TMyThread: : SetName ( ) 

{ 

THREADNAMEJNFO info; 
info.dwType = 0x1000; 
info.szName = "MyThreadName"; 
info.dwThreadlD = -1; 
info.dwFlags = 0; 

__try 

{ 

RaiseExceptionf 0x406Dl388, 0, sizeof ( info) /sizeof (DWORD) , (DWORD* ) &info ); 

} 

__except (EXCEPTION_CONTINUE_EXECUTION) 
{ 
} 

} 

// 

Impostare info .szName al nome della classe thread. 

II debugger rileva l'eccezione e controlla il nome del thread nella struttura che gli e 
stata passata. Durante le operazioni di debug, il debugger mostra il nome del 
thread nel campo Thread ID della finestra Thread Status. 

2 Aggiungere all'inizio del metodo Execute una chiamata al nuovo metodo SetName: 

II 

void __fastcall TMyThread: : Executed 

{ 

SetName ( ) ; 

II place existing Execute method code here 

} 

// 

Assegnazione di nomi differenti a thread simili 

Tutte le istanze di un thread di una stessa classe thread hanno lo stesso nome. 
Tuttavia, in fase di esecuzione, e possibile assegnare un nome diverso a ciascuna 
istanza del thread seguendo questa procedura. 

1 Aggiungere alia classe thread una proprieta ThreadName aggiungendo alia 
definizione della classe quanta segue: 

property AnsiStrmg ThreadName = {read=FName, write =FName } ; 

2 Nel metodo SetName, modificare la riga che riporta: 

info.szName = "MyThreadName"; 

in: 

info.szName = ThreadName; 

3 Quando si crea l'oggetto thread: 
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1 Crearlo in uno stato di sospensione. Consultare "Esecuzione di oggetti thread" 
a pagina 11-12. 

2 Assegnare un nome, come ad esempio MyThread 

MyThread.ThreadName="SearchForFiles" ; 

3 Riprendere il thread. Consultare "Avvio e interruzione dei thread" a 
pagina 11-12. 
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Gestione delle eccezioni 



C++Builder supporta la gestione delle eccezioni C++, la gestione delle eccezioni 
strutturate basata su C e la gestione delle eccezioni VCL e CLX. 

E possibile sollevare qualsiasi eccezione C++ Ansi Standard oltre che eccezioni di 
tipo VCL, le quali includono routine native per la gestione degli errori. 

Viene fornito anche il supporto per le eccezioni strutturate Win32 basate su C, in 
modo che il codice possa reagire correttamente alle eccezioni sollevate dal sistema 
operativo Windows. 

Gestione delle eccezioni C++ 



Le eccezioni sono condizioni eccezionali che richiedono una gestione speciale; 
possono includere errori che si verificano in fase di esecuzione, come una divisione 
per zero o resaurimento della memoria disponibile. La gestione delle eccezioni fornisce 
un modo standard per la gestione degli errori, per scoprire i problemi previsti e 
quelli inattesi, e per consentire agli sviluppatori di riconoscere, di tracciare e di 
correggere gli errori. 

Quando si verifica un errore, il programma solleva un'eccezione. Di solito l'eccezione 
contiene informazioni su cio che e accaduto. Cio permette a un'altra parte del 
programma di diagnosticare la causa dell'eccezione. 

I programmi vengono preparati per le eccezioni inserendo in un blocco try una serie 
di istruzioni che potrebbero provocarle. Se una di queste istruzioni solleva 
un'eccezione, il controllo viene trasferito aungestore di eccezioni che gestisce quel tipo 
di eccezione. Si dice che il gestore di eccezioni intercetta l'eccezione e specifica le 
azioni da eseguire prima di terminare il programma. 
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Sintassi della gestione delle eccezioni 



La gestione delle eccezioni richiede l'uso di tre parole chiave: try, catch e throw. La 
parola chiave throw viene utilizzata per generare un'eccezione. II blocco try contiene 
istruzioni che potrebbero sollevare eccezioni ed e seguito da una o piu istruzioni 
catch. Ogni istruzione catch gestisce un tipo specifico di eccezione. 

Le parole chiave try, catch e throw non sono ammesse nei programmi C. 

II blocco try 

II blocco try contiene un'istruzione o una serie di istruzioni che possono sollevare 
un'eccezione. Un programma segnala un'eccezione eseguendo un'istruzione throw. 
L'istruzione throw generalmente si trova all'interno di una funzione: Per esempio: 

void SetFieldValue(DF *dataField, int userValue) 

{ 

if ((userValue < 0) I I userValue > 10) 
throw EIntegerRange (0, 10, userValue); 

} 

Un'altra parte del programma puo catturare l'oggetto che ha segnalato l'eccezione e 
gestirlo di conseguenza. Per esempio: 

try 

{ 

SetFieldValue (dataField, userValue) ; 

} 

catch (EIntegerRange &rangeErr) 

{ 

prmtf ( "Expected value between Id and %d, but got %d\n", 
rangeErr.min, rangeErr.max, rangeErr. value ) ; 

} 

Nell'esempio precedente, se la funzione SetFieldValue rileva che i suoi parametri di 
input non sono validi, puo sollevare un'eccezione per indicare cio. II blocco try/catch 
include SetFieldValue per intercettare l'eccezione sollevata da SetFieldValue ed esegue 
l'istruzione printf . Se non viene sollevata alcuna eccezione, l'istruzione printf non 
sara eseguita. 

Un blocco try specificato da try deve essere seguito immediatamente dal gestore 
specificato da catch. II blocco try e un'istruzione che specifica il flusso di controllo del 
programma. Se viene segnalata un'eccezione nel blocco try, il controllo del 
programma viene trasferito ad un gestore di eccezione appropriate 

II gestore e un blocco di codice progettato per gestire le eccezioni. II linguaggio C++ 
richiede almeno un gestore immediatamente dopo un blocco try. II programma deve 
includere un gestore per ogni eccezione che puo generare. 

L'istruzione throw 

L'istruzione throw puo innescare diversi tipi di oggetti. Gli oggetti in C++ possono 
essere generalmente innescati per valore, per riferimento o per puntatore. Per 
esempio: 
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// throw an object, to be caught by value or reference 
throw EIntegerRange(0, 10, userValue); 

// throw an object to be caught by pointer 
throw new EIntegerRange (0, 10, userValue); 

I due esempi successivi mostrano funzionalita che vengono fornite in gran parte per 
la completezza nello standard. E preferibile innescare eccezioni piu descrittive. Vi 
sono casi particolari per innescare tipi nativi, come gli integer. Inoltre, e preferibile 
non innescare eccezioni per puntatore. 

// throw an integer 
throw 1; 

// throw a char * 
throw "foo"; 

Nella maggior parte dei casi, si preferira intercettare le eccezioni per riferimento, e in 
particolare mediante riferimenti di tipo const. Vi sono alcuni casi in cui si vorra stare 
attenti ad intercettare oggetti mediante valore. Gli oggetti che vengono intercettati 
mediante valore devono essere copiati prima di poterli assegnare al parametro di 
intercettazione. Se un utente fornisce un costruttore di copia, questo costruttore verra 
chiamato, e cio puo apportare inefficienza. 

L'istruzione catch 

L'istruzione catch ha diverse forme. Gli oggetti possono essere intercettati per valore, 
per riferimento o per puntatore. Inoltre, al parametro catch possono essere applicati i 
modificatori const. Per un singolo blocco try vi possono essere piu istruzioni catch in 
modo da consentire l'intercettazione di piu diversi di eccezioni da parte di un blocco, 
e ci dovrebbe essere un'istruzione catch per ogni eccezione che potrebbe essere 
sollevata. Per esempio: 

try 

Coiranit Change (dataBase, recordMods) ; 
catch (const EIntegerRange SrangeErr) 

printf("Got an integer range exception"); 
catch (const EFileError &fileErr) 

printf ("Got a file I/O error") ; 

Se la funzione CommitChange utilizza piu sottosistemi e questi sottosistemi possono 
innescare vari tipi di eccezioni, si potrebbe voler gestire ogni tipo di eccezione in 
modo separate Con piu istruzioni catch per una singola istruzione try, e possibile 
avere gestori per ogni tipo di eccezione. 

Se un oggetto eccezione e derivato da una classe base, si potrebbero volere 
aggiungere dei gestori specializzati per alcune eccezioni derivate, ma si potrebbe 
voler includere anche un gestore generico per la classe base. L'operazione e fattibile 
collocando delle istruzioni catch nella sequenza con cui si desidera che vengano 
ricercate nel momento in cui viene sollevata un'eccezione. II codice che segue, ad 
esempio, gestisce dapprima EIntegerRange e poi ERange, da cui e derivato 
Einteger Range. 

try 

SetFieldValuefdataField, userValue) ; 
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catch (const EIntegerRange krangeErr) 

printf("Got an integer range exception"); 
catch (const ERange krangeErr) 

printf("Got a range exception"); 

Infine, se si desidera che il gestore intercetti tutte le eccezioni che potrebbero essere 
sollevate dopo il blocco try, si utilizza la forma speciale catch(...). Questa forma dice 
al sistema di gestione delle eccezione che si dovrebbe richiamare il gestore per 
qualsiasi eccezione. Per esempio: 

try 

SetFieldValue(dataField, userValue) ; 
catch (...) 

print f ("Got an exception of some kind"); 

Risollevamento delle eccezioni 



In alcuni casi, un gestore di eccezioni potrebbe elaborare un'eccezione, quindi 
sollevare di nuovo la stessa eccezione o sollevare un'eccezione differente. 

Se il gestore vuole sollevare di nuovo l'eccezione corrente, e sufficiente che utilizzi 
l'istruzione throw senza parametri. In questo modo si dice al compilatore o alia 
libreria RTL di prendere l'oggetto eccezione corrente e sollevarlo di nuovo. Per 
esempio: 

catch (EIntegerRange SrangeErr) 

{ 

// Code here to do local handling for the exception 
throw; // rethrow the exception 

} 

Se il gestore vuole sollevare un'eccezione diversa, e sufficiente che utilizzi solo 
l'istruzione throw nel modo solito. 

Specifica delle eccezioni 



E possibile specificare quali sono le eccezioni che una funzione puo solevare. Se si 
solleva un'eccezione di tipo errato nei confront di una funzione viene generato un 
errore di runtime. La sintassi per la specifica delle eccezioni e: 

exception-specification: 

throw (type-id-list) //type-id-list is optional 
type-id-list : 
type-id 

type-id-list, type-id 
Gli esempi seguenti sono funzioni con specifica delle eccezioni. 

void fl(); // The function can throw any exception 

void f2() throw)); // Should not throw any exceptions 

void f3() throw) A, B* ) ; // Can throw exceptions publicly derived from A, 
// or a pointer to publicly derived B 
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La definizione e tutte le dichiarazioni di tale funzione devono avere una specifica 
delle eccezioni contenente lo stesso gruppo di type-id. Se una funzione segnala 
un'eccezione non contenuta nella sua specifica, il programma chiamera unexpected. 

E possibile che non si voglia specif icare un'eccezione per i seguenti motivi: 

Anzitutto, in Windows vi e un calo delle prestazioni runtime legato alia specifica 
delle eccezione in una funzione. 

In secondo luogo, e possibile ottenere errori inattesi in esecuzione. Ad esempio, si 
supponga che il sistema utilizzi la specifica delle eccezioni e utilizzi un altro 
sottosistema nella sua implementazione. Ora si supponga che il sottosistema venga 
modificato in modo che sollevi nuovi tipi di eccezione. Quando si utilizza il nuovo 
codice del sottosistema, si potrebbero ottenere errori di runtime senza ottenere mai 
dal compilatore un'indicazione che cio potrebbe accadere. 

Infine, se si utilizzano funzioni virtuali, e possibile violare il progetto del 
programma. Cio e dovuto al fatto che la specifica delle eccezioni non e considerata 
parte del tipo della funzione. Nell'esempio seguente la classe derivata BETA::vfunc e 
definita in modo tale da non segnalare nessuna eccezione — una deviazione rispetto 
alia dichiarazione originale della funzione. 

class ALPHA { 
public: 

Struct ALPHA_ERR {}; 

virtual void vfunc(void) throw (ALPHA_ERR) {} // Exception specification 

}; 

Class BETA : public ALPHA { 
void vfunc (void) throw () {} // Exception specification is changed 

}; 

Rilascio delle eccezioni 



Quando viene sollevata un'eccezione, la libreria runtime prende l'oggetto che e stato 
sollevato, ottiene il tipo dell'oggetto e guarda nello stack delle chiamate alia ricerca di 
un gestore il cui tipo corrisponda al tipo dell'oggetto gettato. Una volta trovato un 
gestore, la RTL rilascia lo stack fino al punto del gestore e lo esegue. 

Nel processo di rilascio, la RTL chiama i distruttori per tutti gli oggetti locali presenti 
nei frame dello stack dal punto in cui l'eccezione e stata sollevata fino al punto in cui 
e stata intercettata. Se un distruttore provoca il sollevamento di un'eccezione durante 
il rilascio dello stack e non la gestisce, viene chiamata la funzione terminate. I 
distruttori vengono chiamati per impostazione predefinita, ma e possibile disattivare 
questo comportamento predefinito utilizzando l'opzione -xd del compilatore. 

Puntatori sicuri 

Nel caso si abbiano variabili locali che sono puntatori a oggetti e viene sollevata 
un'eccezione, questi puntatori non vengono cancellati automaticamente. Cio accade 
perche il compilatore poiche non ha alcun modo per distinguere fra un puntatore ai 
dati, allocate) solo per questa funzione, e un qualsiasi altro puntatore. La classe che e 
possibile utilizzare, per essere certi che gli oggetti allocati per un utilizzo locale siano 
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distrutti nel caso in cui si verifichi un'eccezione, e auto_ptr. C'e un caso particolare in 
cui la memoria per un puntatore allocate) in una funzione viene liberata: 

TMyObject *pMyObject = new TMyObject; 

In questo esempio, se il costruttore per TMyObject solleva un'eccezione, il puntatore 
all'oggetto allocato per TMYObject sara cancellato dalla RTL nel momento in cui 
rilascia l'eccezione. Questo e l'unico caso in cui il compilatore cancella 
automaticamente un valore di puntatore. 

I costruttori nella gestione delle eccezioni 



I costruttori delle classi possono segnalare eccezioni se non sono in grado di costruire 
un oggetto. Se un costruttore segnala un'eccezione, non viene chiamato 
necessariamente il distruttore dell'oggetto. I distruttori vengono chiamati solo per le 
classi base e per gli oggetti che sono stati completamente costruiti all'interno delle 
classi a partire dall'ingresso nel blocco try. 

Gestione di eccezioni non intercettate e inattese 



Se viene sollavata un'eccezione e non viene trovato nessun gestore dell'eccezione — 
cioe, l'eccezione non viene intercettata — il programma chiama una funzione di 
terminazione. E possibile specificare una propria funzione di terminazione con 
set_terminate. Se non si specifica una funzione di terminazione, viene chiamata la 
funzione terminate. Per esempio, il codice seguente utilizza la funzione my_terminate 
per gestire le eccezioni non intercettate da alcun gestore. 

void SetFieldValue(DF MataField, int userValue) 

{ 

if ((userValue < 0) I I (userValue) > 10)); 
throw EIntegerRange(0, 10, userValue); 

} 

void my_terminate() 
{ 

printf ( "Exception not caught"); 
abort ( ) ; 

} 

// Set my_termmate ( ) as the termination function 
set_terminate (my_terminate) ; 

// Call SetFieldValue. This generates an exception because the user value is greater 
// than 10. Because the call is not in a try block, my_terminate is called. 
SetFieldValue (DF, 11); 

Se una funzione specifica quali sono le eccezioni sollevate e solleva un'eccezione non 
specificata, viene chiamata una funzione unexpected. E possibile specificare la 
funzione unexpected con set_unexpected. Se non si specifica una funzione unexpected, 
viene chiamata la funzione unexpected. 
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Eccezioni strutturate in ambiente Win32 



Win32 supporta la gestione delle eccezioni strutturate basate su C, che sono simili 
alle eccezioni di C++. Esistono, comunque, alcune differenze fondamentali che 
richiedono un utilizzo attento quando vengono mescolate con codice C++ per la 
gestione delle eccezioni. 

Quando si utilizza la gestione delle eccezioni strutturate nelle applicazioni 
C++Builder, occorre tenere presente quanta segue: 

• Le eccezioni strutturate del C possono essere utilizzate in programmi C++. 

• Le eccezioni C++ non possono essere utilizzate in programmi C, in quanta 
richiedono che il loro gestore sia specificato tramite la parola chiave catch, e catch 
non e consentita nei programmi C. 

• Un'eccezione generata da una chiamata alia funzione RaiseException viene gestita 

mediante il blocco try/ except (C++) o try/ except (C). (Si possono anche 

utilizzare i blocchi try/ finally oppure try/ finally. Vedere "Sintassi delle 

eccezioni strutturate" a pagina 12-7.) Tutti i gestori dei blocchi try/catch vengono 
ignorati quando viene chiamata la funzione RaiseException. 

• Le eccezioni che non sono gestite dalle applicazioni non generano una chiamata a 
terminateO, ma vengono passate invece al sistema operativo (in generale, il 
risultato finale e la fine del processo). 

• I gestori di eccezioni non ricevono una copia dell'oggetto eccezione, a meno che 
non la richiedano. 

Nei programmi C e C++ si possono utilizzare le seguenti funzioni di supporto delle 
eccezioni C: 

• GetExceptionCode 

• GetExceptionlnformation 

• SetUnhandledExceptionFilter 

• UnhandledExceptionFilter 

C++Builder non limita l'utilizzo della funzione UnhandledExceptionFilter al filtro di 

eccezione dei blocchi try/_except o try/ except. Comunque, il comportamento 

del programma non e definito quando questa funzione viene chiamata al di fuori del 
blocco try/ except o try/ except. 

Le applicazioni CLX in esecuzione su Linux non supportano eccezioni strutturate C / 
C++. 



Sintassi delle eccezioni strutturate 



In un programma C le parole chiave ANSI compatibili utilizzate per implementare le 
eccezioni strutturate sono except, finally e try. 

La parola chiave try pud apparire soltanto in programmi C. Se si vuole scrivere del 

codice portabile, nei programmi C++ non si deve utilizzare la gestione delle eccezioni 
strutturate. 
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Sintassi per la gestione delle eccezioni try-except 

La sintassi per la gestione delle eccezioni try-except e la seguente: 

blocco try: 

lstruzione composta try (in un modulo C) 

lstruzione composta try (in un modulo a C++) 
gestore: 

..except (espressione) istruzione composta 

Sintassi della terminazione try-finally 

Nel caso della terminazione try-finally la sintassi e:: 

blocco try: 

istruzione composta __try (in un modulo C) 

istruzione composta try (in un modulo a C++) 
terminazione: 

__finally istruzione composta 



Gestione delle eccezioni strutturate 



Le eccezioni strutturate possono essere gestite utilizzando un'estensione della 
gestione delle eccezioni di C++: 

try { 

food; 

} 

__except (__expr__) { 
// handler here 

} 

__expr__ e un'espressione che puo assumere uno dei tre valori seguenti: 



Valore 

EXCEPTION_CONTINUE_SEARCH (0) 

EXCEPTION jZONTINUE_EXECUTION(-l) 
EXCEPTION_EXECUTE_HANDLER (1) 



Descrizione 

II gestore delle eccezioni non e stato indicato e il 
sistema operativo continua a cercarlo. 

Continua l'esecuzione nel punto dell'eccezione. 

Attiva il gestore delle eccezioni. Se il codice e stato 
compilato con il distruttore di cleanup abilitato (- 
xd, opzione attiva per impostazione predefinita), 
tutti i distruttori per gli oggetti locali creati tra il 
punto di eccezione e il gestore di eccezioni vengono 
chiamati quando viene scaricato lo stack. Lo scarico 
dello stack viene completato prima dell'attivazione 
del gestore. 



Win32 fornisce due funzioni che possono essere utilizzate per ricercare informazioni 
sull'eccezione attiva: GetExceptionCodeO e GetExceptionlnformationO. Se si vuole 
chiamare una funzione come parte dell'espressione "filtro" sopra indicata, queste 
funzioni devono essere chiamate direttamente dall'interno del contesto di exceptQ: 

♦include <Windows.h> 
iinclude <excpt.h> 
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int filter_func(EXCEPTION_POINTERS *); 

EXCEPTION. POINTERS *xp = 0; 
try { 

food; 

} 

__except (f ilter_func (xp = GetExceptionInformation() ) ) { 
//... 

} 

Oppure, se si preferisce utilizzare l'operatore virgola per assegnazioni annidate nelle 
chiamate a funzioni, vedere l'esempio seguente: 

__except((xp = GetExceptionlnformationO ) , filter_func (xp) ) 

Filtri delle eccezioni 



Un'espressione filtro puo richiamare una funzione filtro, ma la funzione filtro non 
puo chiamare GetExceptionlnformation. E possibile passare alia funzione filtro il valore 
restituito da GetExceptionlnformation come parametro. 

Per passare l'informazione EXCEPTION_POINTERS ad un gestore di eccezioni, 
l'espressione o la funzione filtro devono copiare il puntatore o i dati da 
GetExceptionlnformation in una posizione a cui il gestore puo accedere 
successivamente. 

Nel caso di istruzioni try-except annidate, ogni espressione filtro dell'istruzione 
viene valutata f inche non viene individuato EXCEPTION_EXECUTE_HANDLER o 
EXCEPTION_CONTINUE_EXECUTION. Un'espressione filtro puo richiamare 
GetExceptionlnformation per ottenere informazioni sull'eccezione. 

A patto che GetExceptionlnformation o GetExceptionCode siano chiamate direttamente 

nell'espressione fornita a except, si puo usare una funzione per determinare cosa 

fare con un'eccezione anziche tentare di creare un'espressione C++ complessa. Quasi 
tutte le informazioni necessarie per gestire un'eccezione possono essere ricavate dal 
risultato di GetExceptionlnformationO. GetExceptionlnformationO restituisce un 
puntatore ad una struttura EXCEPTION_POINTERS: 

Struct EXCEPTION_POINTERS { 

EXCEPTION_RECORD *ExceptionRecord; 
CONTEXT "Context; 

}; 

EXCEPTION_RECORD contiene la stato indipendente dalla macchina: 

Struct EXCEPTION_RECORD { 

DWORD Except lonCode; 

DWORD ExceptionFlags; 

struct EXCEPTIOSLRECORD *ExceptionRecord; 

void *ExceptionAddress; 

DWORD NumberParameters; 

DWORD Except ionlnformat ion [EXCEPTION_MAXIMUM_PARAMETERS] ; 

}; 
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Generalmente, la funzione filtro analizza le informazioni contenute in 
ExceptionRecord per decidere come rispondere. Talvolta si ha bisogno di 
informazioni piu specifiche (specialmente se l'azione da intrapendere e 
EXCEPTION_CONTINUE_EXECUTION: se non si fa nulla, il codice che ha causato 
l'eccezione sara eseguito nuovamente). In questi casi, l'altro campo della struttura 
EXCEPTION_POINTERS fornisce lo stato del processore al momento dell'eccezione. 
Se questa struttura viene modificata e il filtro restituisce 

EXCEPTION_CONTINUE_EXCEPTION, tale valore viene usato per impostare lo 
stato del thread prima di procedere con l'esecuzione. Per esempio: 

static int xf ilter (EXCEPIION.POINTERS *xp) 
{ 

int rc; 

EXCEPTION.RECORD *xr = xp->ExceptionRecord; 
CONTEXT *xc = xp->Context; 

switch (xr->ExceptionCode) { 
case EXCEPTION. BREAKPOINT : 

// whoops, someone left an embedded breakpoint. 
// just step over it (1 byte on x86) 
++xc->Eip; 

rc = EXCEPIION.CONIINUE.EXECUIION; 
break; 

case EXCEPTION. ACCESS.VIOLATION: 

rc = EXCEPTION_EXECUTE_HANDIER; 

break; 

default : 

// give up 

rc = EXCEPTION.CONIINUE.SEARCH; 
break; 

}; 

return rc; 

} 



EXCEPTION.POINIERS *xp ; 

try { 

f unc ( ) ; 

} 

..except (xf ilter (xp = GetExceptionlnformation ( ) ) ) { 
abort ( ) ; 

} 

Abbinamento di eccezioni strutturate con C++ 



Bisogna essere consapevoli delle conseguenze derivanti dall'utilizzo delle eccezioni 
strutturate nei programmi C++. Innanzi tutto, anche se C++Builder implementa le 



12-10 Guida alia programmazione 



Eccezioni strutturate in ambiente Win32 

eccezioni C++ con le eccezioni strutturate Win32, le eccezioni C++ sono trasparenti 
ad un blocco except. 

Un blocco try puo essere seguito esattamente da un blocco except o da almeno un 
blocco catch. II tentativo di abbinarli genera un errore in fase di compilazione. II 
codice necessario per gestire entrambi i tipi di eccezione deve essere semplicemente 
annidato all'interno di due blocchi try: 

try { 

EXCEPTION_POINTERS *xp; 

try { 

func ( ) ; 

} 

__except (xfilterfxp = GetExceptionlnformation ( ) ) ) { 
//... 

} 

} 

catch (...) { 
//... 

} 

La specifica di una funzione throw() non incide sul comportamento di un programma 
rispetto ad un'eccezione Win32. Inoltre, un'eccezione non gestita viene 
eventualmente gestita dal sistema operativo (se un debugger non la gestisce prima), a 
differenza di quanto fanno i programmi C++ che chiamano terminateQ. 

Tutti i moduli compilati con l'opzione -xd del compilatore (attiva per impostazione 
predefinita) richiameranno i distruttori di tutti gli oggetti con memorizzazione di 
tipo auto. Si ha lo scarico dello stack dal punto in cui si e verificata l'eccezione fino al 
punto in cui essa viene catturata. 

Eccezioni basate su C in un programma di esempio C++ 

/* Program results : 

Another exception: 

Caught a C-based exception. 

Caught C++ exception [Hardware error: Divide by 0] 

C++ allows finally too! 

*/ 

♦include <stdio.h> 
♦include <string.h> 
♦include <windows.h> 

class Exception 
{ 

public: 

Exception (char* s = "Unknown")} what = strdup(s); } 
Exception (const Exceptions e ){ what = strdup (e.what) ; } 
-Exception () { deleted what; } 

char* msg() const { return what; } 

private: 
char* what; 

}; 
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int main() 

{ 

float e, f, g; 

try 

{ 

try 

{ 

f = 1.0; 
g = 0.0; 

try 
{ 

puts ( "Another exception:"); 

e = f / g; 

} 

__except (EXCEPTION. EXECUTE_HANDLER) 

{ 

puts ( "Caught a C-based exception."); 

throw (Exception) "Hardware error: Divide by 0")); 

} 

} 

catch (const Exceptions e) 
{ 

printf ( "Caught C++ Exception: Is :\n", e.msgO); 

} 

} 

finally 

{ 

puts ("C++ allows __finally too!"); 

} 

return e; 

} 

Definizione delle eccezioni 



Sollevare un'eccezione Win32 che viene gestita all'interno dello stesso programma 
generalmente non ha molto senso: le eccezioni C++ possono fare di meglio, risultano 
molto piu portabili e utilizzano una sintassi piu semplice. Le eccezioni Win32 offrono 
comunque il vantaggo che possono essere gestite da componenti che potrebbero non 
essere stati compilati con lo stesso compilatore C++. 

II primo passo consiste nel definire l'eccezione. Un' eccezione e un intero a 32 bit con 
il seguente formato (a partire dal bit 0): 

Bit Significato 

31-30 11 = Errore (normale) 

00 = Esito positivo, 

01 = Informazione 

10 = Avvertenza 

29 1 = Definito 

dall'utente 
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Bit Significato 

28 Riservato 

27-0 Definito dall'utente 

Oltre alia definizione del codice dell'eccezione, occorre decidere se includere o meno 
informazioni addizionali sull'eccezione (accessibile al filtro/ gestore dal record di 
eccezione). Non ci sono metodi convenzionali per codificare altri parametri nel 
codice dell'eccezione. Per maggiori informazioni, consultare la documentazione su 
Win32 (disponibile nella Guida in linea di C++Builder). 

Sollevamento delle eccezioni 



Un'eccezione Win32 viene sollevata mediante una chiamata a RaiseExceptionQ, la 
quale viene dichiarata come segue 

void RaiseException (DWORD ec, DWORD ef, DWORD na, const DWORD *a); 
dove: 

ec Codice di eccezione 

ef Exception flags, either or EXCEPTION J^ONCONTINU ABLE 

(Flag di eccezione; assume il valore o EXCEPTION_NONCONTINUABLE. (Se l'eccezione 
viene contrassegnata come non continuabile e un filtro prova a continuarla, viene sollevata 
EXCEPTION_NONCONTINUABLE„EXCEPTION.) 

na Numero di elementi dell'array di argomenti 

a Puntatore al primo elemento dell'array di argomenti-il significato di questi argomenti 
dipende dalla specifica eccezione 

Blocchi di terminazione 



II modello di gestione delle eccezioni strutturate supporta un "blocco di 
terminazione", che viene eseguito sia che si esca normalmente da un blocco 
controllato sia che si esca mediante un'eccezione. II compilatore di C++Builder lo 
supporta in C con la seguente sintassi: 

__try { 

func ( ) ; 

} 

finally { 

// this happens whether funcO raises an exception or not 

} 

I blocchi di terminazione sono supportati da un'estensione C++ dove e possibile 
gestire le operazioni di pulizia nel blocco finally: 

try { 

func ( ) ; 

} 

finally { 
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// this happens whether funcO raises an exception or not 

} 

L'esempio seguente illustra i blocchi di terminazione: 

/* Program results : 
An exception: 
Caught an exception. 

The finally is executed too! 

No exception: 

No exception happened, but __finally still executes! 
V 

♦include <stdio.h> 
♦include <windows.h> 

int main() 

{ 

float e, f, g; 

try 

{ 

f = 1.0; 
g = 0.0; 

try 
{ 

puts ( "An exception: " ) ; 

e = f / g; 

} 

__except ( EXCEPTION_EXECUTE_HANDLER) 
{ 

puts ( "Caught an exception."); 

} 

} 

finally 

{ 

puts ("The __finally is executed too!"); 

} 

try 

{ 

f = 1.0; 
g = 2.0; 

try 
{ 

puts ( "No exception: " ) ; 

e = f / g; 

} 

__except ( EXCEPTION_EXECUTE_HANDLER) 

{ 

puts ( "Caught an exception."); 

} 

} 

finally 

{ 

puts ("No exception happened, but __finally still executes!"); 

} 
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return e; 

} 

II codice C++ puo anche gestire un "blocco di terminazione" creando oggetti locali 
con i distruttori che vengono chiamati quando si esce dal campo d'azione. Dato che le 
eccezioni strutturate di C++Builder supportano le operazioni di pulizia del 
distruttore, questo funzionera indipendentemente dal tipo di eccezione che si e 
verificata. 

Si ha una situazione particolare nel caso in cui si verifica un'eccezione non gestita dal 
programma. Per un'eccezione C++ il compilatore di C++Builder chiama i distruttori 
degli oggetti locali (non richiesto dalla definizione del linguaggio), mentre con 
un'eccezione Win32 non gestita l'operazione di pulzia del distruttore non avviene. 

Opzioni di C++Builder per la gestione delle eccezioni 



Di seguito sono riportate le opzioni di gestione delle eccezioni del compilatore di 
C++Builder. 

Tabella 12.1 Opzioni del compilatore per la gestione delle eccezioni 
Opzione della 

riga comandi Descrizione 

-x Abilita la gestione delle eccezioni di C++ (Attiva per impostazione 

predefinita)) 

-xd Abilita la cancellazione da parte del distruttore. Chiama i distruttori di tutti gli 

oggetti dichiarati in modo automatico all'interno del campo d'azione delle 
istruzioni catch e throw quando viene segnalata un'eccezione. (Opzione 
evoluta-attiva per impostazione predefinita) 

-xp Abilita le informazioni sulla posizione dell'eccezione. Rende disponibile in 

fase di esecuzione 1'identificazione delle eccezioni fornendo i numeri di riga 
nel codice sorgente in cui e si trova l'eccezione. Cio consente al programma di 
individuare il file e il numero di riga in cui si e verificata un'eccezione C++ 

usando le definizioni globali ThrowFileName e ThrowLineNumber. 

(Opzione evoluta) 



Gestione delle eccezioni VCL/CLX 



Quando nelle proprie applicazioni si utilizzano componenti VCL/CLX, occorre 
comprendere il relativo meccanismo per la gestione delle eccezioni. Le eccezioni 
sono, infatti, integrate in molte classi e vengono segnalate automaticamente quando 
avviene qualcosa di inatteso. Se non si gestisce l'eccezione, la VCL e la CLX la gestira 
in maniera predefinita. Generalmente viene visualizzato un messaggio che descrive il 
tipo di errore verificatosi. 

Quando in fase di stesura del programma si incontra un'eccezione che visualizza un 
messaggio che indica il tipo di eccezione che e stata segnalata, e possibile controllare 
la classe dell'eccezione nella Guida in linea. Le informazioni fornite spesso 
permettono di determinare dove si e verificato l'errore e quale ne e la causa. 
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Inoltre, nel Capitolo 13, "Supporto del linguaggio C++ per la VCL e la CLX" vengono 
descritte le sottili differenze di linguaggio che possono provocare eccezioni. La 
sezione "Eccezioni sollevate dai costruttori" a pagina 13-14 riporta un esempio che 
mostra cosa accade se viene sollevata un'eccezione durante la costruzione di un 
oggetto. 

Differenze tra C++ e VCL/CLX nella gestione delle eccezioni 



Di seguito sono riporta te alcune differenze molto importanti tra notevoli tra C++ e 
VCL/ CLX nella gestione delle eccezioni. 

Eccezioni sollevate dai costruttori: 

• I distruttori C++ vengono chiamati per i membri e le classi basi che sono stati 
completamente costruiti. 

• I distruttori della classe base VCL vengono chiamati anche se l'oggetto o la classe 
base non sono stati completamente costruiti. 

Intercettazione e sollevamento di eccezioni: 

• Le eccezioni C++ possono essere intercettate per riferimento, per puntatore o per 
valore. Le eccezioni VCL o CLX, che sono eccezioni derivate da TObject, possono 
essere catturate solo per riferimento o per puntatore. II tentativo di interettare le 
eccezioni di TObject per valore restituisce un errore in fase di compilazione. Le 
eccezioni dell'hardware o del sistema operative come EAccessViolation, devono 
essere intercettate per riferimento. 

• Le eccezioni VCL e CLX vengono intercettate per riferimento. 

• Non si puo utilizzare throw per sollevare nuovamente un'eccezione che e stata 
intercettata all'interno del codice VCL o CLX. 

Gestione delle eccezioni del sistema operativo 



C++Builder permette di gestire le eccezioni segnalate dai sistema operativo. Queste 
includono le violazioni di accesso, gli errori matematici sugli interi, gli errori 
matematici in virgola mobile, l'overflow dello stack e gli interrupt di Ctrl+C. Tali 
eccezioni vengono gestite in RTL C++ e convertite in oggetti di classe eccezione della 
VCL prima di essere inviate all'applicazione. Si puo scrivere del codice come questo: 

try 
{ 

char * p = 0; 

*p = 0; 

} 

// You should always catch by reference. 

catch (const EAccessViolation &e) 

{ 

printf("You can't do that!\n"); 

} 
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Le classi utilizzate da C++Builder sono le stesse utilizzate da Delphi e sono 
disponibili soltanto per le applicazioni VCL e CLX di C++Builder. Sono derivate da 
TObject e richiedono di appoggiarsi alia VCL o alia CLX. 

Di seguito sono riportate alcune caratteristiche della gestione delle eccezioni di 
C++Builder: 

• Non si e responsabili del rilascio dell'oggetto eccezione. 

• Le eccezioni del sistema operativo devono essere intercettate per riferimento. 

• Non si puo sollevare di nuovo un'eccezione di sistema operativo una volta che si e 
usciti dal frame di intercettazione e l'operazione di intercettazione e stata 
effettuata tramite i frame di intercettazione della VCL o della CLX. 

• Non si puo sollevare di nuovo un'eccezione di sistema operativo una volta che si e 
usciti dal frame di intercettazione e l'operazione di intercettazione e stata 
effettuata tramite i frame di intercettazione del sistema operativo. 

Gli ultimi due punti possono essere sintetizzati in questo modo: una volta che 
l'eccezione di sistema operativo e stata intercettata come un'eccezione C++, essa non 
puo essere sollevata di nuovo come un+eccezione di sistema operativo o come 
un+eccezione della VCL o della CLX, a meno che non ci si trovi nella struttura dello 
stack di intercettazione. 

Gestione delle eccezioni della VCL e della CLX 



C++Builder amplia la semantica per la gestione delle eccezioni software sollevate 
dalla VCL e dalla CLX o, analogamente, delle eccezioni sollevate da C++, in cui la 
classe di eccezione da sollevare e derivata da TObject. In questo caso, si applica una 
coppia di regole derivanti dal fatto che le classi in stile VCL possono essere allocate 
solo nello heap. 

• Le classi di eccezione in stile VCL possono essere intercettate solo per puntatore, 
se si tratta di un'eccezione software, o per riferimento (che e la modalita preferita). 

• Un'eccezione in stile VCL deve essere sollevata mediante la sintassi "per valore". 

Classi di eccezioni VCL e CLX 



C++Builder include un vasto gruppo di classi di eccezione native per la gestione 
automatica degli errori di divisione per zero, degli errori di I/O su file, degli errori di 
conversione di tipo e di molte altre condizioni di eccezione. Tutte le classi di 
eccezione VCL e CLX discendono da un oggetto radice di nome Exception. Exception 
incapsula le proprieta fondamentali e i metodi per tutte le eccezioni ti tipo VCL e 
fornisce un'interfaccia compatibile in modo che le applicazioni gestiscano le 
eccezioni. 

Le eccezioni possono essere passate ad un blocco catch che accetta un parametro di 
tipo Exception. Per intercettare le eccezioni VCL e CLX, utilizzare la seguente sintassi: 

catch (exception_class &exception_variable) 
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Si deve specificare la classe di eccezione che si vuole intercettare e fornire una 
variabile tramite la quale fare riferimento all'eccezione. 

L'esempio seguente mostra come sollevare un' eccezione VCL o CLX: 

void fastcall TForml: :ThrowException(TObject *Sender) 

{ 

try 

{ 

throw Exception ( "An error has occurred"); 

} 

catch (const Exception &E) 
{ 

ShowMessage(AnsiString(E.ClassName() )+ E. Message) ; 

} 

} 

L'istruzione throw nell'esempio precedente crea un'istanza della classe Exception e 
chiama il suo costruttore. Tutte le eccezioni che discendono da Exception hanno un 
messaggio che puo essere visualizzato, passato attraverso i costruttori, e recuperato 
tramite la proprieta Message. 

Le classi di eccezione VCL/CLX selezionate sono descritte nella Tabella 12.2. 
Tabella 12.2 Classi di eccezione selezionate 



Classe di 




eccezione 


Descrizione 


EAbort 


Interrompe una sequenza di eventi senza visualizzare una finestra di 




dialogo con un messaggio di errore. 


EAccessViolation 


Controlla gli errori di accesso non valido alia memoria. 


EBitsError 


Impedisce tentativi di accesso non valido agli array booleani. 


EComponen tError 


Segnala un tentativo di registrare o di rinominare un componente. 


EConvertError 


Indica errori di conversione di oggetti o di stringhe. 


EDatabaseError 


Specifica un errore di accesso al database. 


EDBEditError 


Cattura i dati incompatibili con una maschera specificata. 


EDivByZero 


Cattura gli errori di divisione per zero. 


EExternalException 


Indica un codice di eccezione non riconosciuto. 


EInOutError 


Rappresenta un errore di I/O su file. 


EInt Overflow 


Specifica calcoli interi i cui risultati sono troppo grandi per il registro 




allocato register. 


EInvalidCast 


Controlla gli errori di conversione di tipo non consentito. 


EInvalidGraphic 


Indica un tentativo di operare con un formato grafico non riconosciuto. 


EInvalidOperation 


Si verifica quando si tentano operazioni non consentite su un componente. 


EInvalidPointer 


Risultato di operazioni di puntatore non valide. 


EMenuError 


E relativo a un problema con una voce di menu. 


EOleCtrlError 


Rivela problemi con i collegamenti ai controlli ActiveX. 


EOleError 


Specifica errori di automazione OLE. 


EPrinterError 


Segnala un errore di stampa. 
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Tabella 12.2 Classi di eccezione selezionate 
Classe di 

eccezione Descrizione 

EPropertyError Si verifica per un tentativo non riuscito di impostare il valore di una 
proprieta. 

ERangeError Indica un valore intero troppo grande per il tipo dichiarato a cui e stato 

assegnato. 

ERegistryException Specifica errori di registro. 

EZeroDivide Cattura gli errori di divisione per zero in virgola mobile. 



Come si puo osservare dall'elenco sopra riportato, le classi di eccezione VCL e CLX 
native gestiscono la maggior parte delle eccezioni, semplificando cosi il codice. Vi 
sono altri casi in cui sara necessario creare delle proprie classi per gestire situazioni 
particolari. E possibile dichiarare una nuova classe di eccezioni facendola discendere 
dal tipo Exception e creando tutti i costruttori necessari (o copiandoli da una classe 
esistente in Sysutils.hpp). 



Considerazioni sulla portability 



Con C++Builder vengono fornite diverse librerie runtime (RTL). La maggior parte di 
esse riguardano le applicazioni C++Builder, ma una (cw32mt.lib) e la normale RTL 
multi-thread che non fa alcun riferimento alia VCL o alia CLX. Questa RTL viene 
fornita per il supporto di applicazioni preesistenti che devono essere inserite in un 
progetto, ma che non devono dipendere dalla VCL. Questa RTL non e in grado di 
gestire le eccezioni del sistema operativo, perche si tratta di oggetti eccezione derivati 
da TObject e richiederebbe che l'applicazione venisse collegata con parti della VCL o 
della CLX. 

E possibile utilizzare la libreria cp32mt.lib una libreria runtime multi-thread che 
fornisce la gestione della memoria e la gestione delle eccezioni con la VCL e la CLX. 

E possibile utilizzare due librerie di importazione, cw32mti.lib e cp32mti.lib, per 
l'utilizzo della DLL della RTL. Utilizzare cp32mti.lib per il supporto delle eccezioni 
VCL e CLX. 
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Capitolo 




Supporto del linguaggio C++ per la 

VCL e la CLX 

C++Builder sfrutta le funzionalita Rapid Application Development (RAD) della 
Visual Component Library (VCL) e della Component Library for Cross-Platform 
(CLX) scritta in Object Pascal. Questo capitolo spiega come le funzionalita, i costrutti 
e i concetti del linguaggio Object Pascal sono stati implementati in C++Builder in 
modo da supportare la VCL e la CLX. Queste pagine sono rivolte ai programmatori 
che usano oggetti VCL e CLX nelle loro applicazioni e agli sviluppatori che creano 
nuove classi derivate da classi VCL e CLX. 

Nella prima parte di questo capitolo vengono confrontati i modelli degli oggetti C++ 
e Object Pascal, e viene descritto il modo in cui C++Builder abbina questi due 
approcci. Nella seconda parte del capitolo viene illustrate) il modo in cui i costrutti 
del linguaggio Object Pascal vengono tradotti in C++ e in C++Builder. Vi sono 
riportate informazioni dettagliate sulle estensioni delle parole chiave che sono state 
aggiunte per supportare la VCL e la CLX. Alcune di queste estensioni, come closure e 
proprieta, sono utili funzionalita, indipendenti dal supporto al codice basato su VCL. 

I riferimenti alle classi C++ derivate da TObject riguardano le classi per le quali 
TObject e il migliore antenato, ma non necessariamente il genitore da cui discendono 
direttamente. Per coerenza con la diagnostica del compilatore a queste classi viene 
anche fatto riferimento come a "classi in stile VCL". 

Modelli di oggetti C++ e Object Pascal 



I modelli delle classi C++ e Object Pascal presentano diversita sia molto evidenti sia 
sottili. Una delle differenze piu evidenti e che C++ consente l'eredita multipla mentre 
Object Pascal e limitato a un modello di eredita singola. Inoltre, C++ e Object Pascal 
presentano delle piccole differenze nel modo in cui creano, inizializzano, fanno 
riferimento, copiano e distruggono gli oggetti. In questa sezione vengono descritte 
queste differenze e il loro impatto sulle classi stile VCL di C++Builder. 
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Eredita e interfacce 



A differenza di C++, il linguaggio Object Pascal non supporta l'eredita multipla. 
Qualsiasi classe creata che abbia come antenati della VCL o della CLX eredita questa 
limitazione. Cio significa che e impossibile utilizzare piu classi di base per una classe 
C++ in stile VCL, anche nel caso in cui la classe VCL o CLX non sia l'antenato 
immediato. 

Utilizzo delle interfacce invece dell'eredita multipla 

Per molte situazioni in cui in C++ si utilizzerebbe l'eredita multipla, il codice Object 
Pascal utilizza invece le interfacce. Non esiste alcun costrutto in C++ che corrisponde 
direttamente al concetto di interfaccia dell' Object Pascal. Un'interfaccia Object Pascal 
agisce come una classe senza implementazione. Cioe significa che un'interfaccia e 
simile a una classe in cui tutti i metodi sono pure virtual e non esiste alcun membro 
dati. Mentre una classe Object Pascal puo avere solo una singola classe genitore, puo 
supportare un numero qualsiasi di interfacce. II codice Object Pascal puo assegnare 
un'istanza di classe a variabili di uno qualunque di quei tipi di interfaccia, 
esattamente come puo assegnare l'istanza di classe a una variabile di qualsiasi tipo di 
classe antenato. Cio consente il comportamento polimorfo per quelle classi che 
condividono la stessa interfaccia, anche se esse non hanno un antenato comune. 

In C++Builder, il compilatore riconosce le classi che hanno solo metodi pure virtual e 
non hanno alcun membro dati come corrispondenti a interfacce di Object Pascal. 
Pertanto, quando si crea una classe in stile VCL, e consentito utilizzare l'eredita 
multipla, ma solo se tutte le classi di base, tranne quella che e una classe della VCL, 
della CLX o in stile VCL, non hanno alcun membro dati e hanno solo metodi pure 
virtual. 

Non e necessario che le classi dell'interfaccia siano classi in style VCL, l'unico 
requisito e che esse non abbiano alcun membro dati e abbiano solo metodi pure 
virtuale. 

Dichiarazione delle classi interfaccia 

E possibile dichiarare una classe che rappresenta un'interfaccia esattamente come 
qualsiasi altra classe C++. Tuttavia, utilizzando alcune convenzioni, e possibile 
rendere piu chiaro che la classe e progettata per agire come un'interfaccia. Queste 
convenzioni sono le seguenti: 

• Invece di utilizzare la parola chiave class, le interfacce vengono dichiarate 

utilizzando interface. interface e una macro che corrispondere con la parola 

chiave class. Non e necessario, ma rende piu chiaro che la classe e progettata per 
agire come un'interfaccia. 

• Di soli to le interfacce hanno nomi che iniziano con la lettera T. Esempi di 
interfaccia sono IComponentEditor o IDesigner. Se si segue questa convenzione, non 
e necessario controllare la dichiarazione della classe per percepire che la classe sta 
agendo come un'interfaccia. 

• Di solito le interfacce hanno un GUID associate Questo non e un requisito 
assoluto, ma la maggior parte del codice che supporta le interfacce si aspetta di 
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trovare un GUID. + possibile utilizzare il modificatore declspec con l'argomento 

uuid per associare un'interfaccia con un GUID. Nel caso delle interfacce, la macro 
INTERFACEJJUID mappa alia stessa cosa. 

La seguente dichiarazione di interfaccia illustra queste convenzioni: 

__interface INTERFACE_UUID ( " {C527B88F-3F8E-1134-80e0-0 1A04F57B2 70} " ) IHelloWorld : 
public Ilnterface 

{ 

public : 

virtual void stdcall SayHelloWorld(void) = ; 

}; 

Di solito, quando si dichiara una classe interfaccia, il codice C++Builder dichiara 
anche una classe Delphilnterface corrispondente che semplifica l'operativita con 
l'interfaccia: 

typedef System: :DelphiInterface< IHelloWorld > _di_IHelloWorld; 

Per informazioni sulla classe Delphilnterface, vedere "Interfacce Delphi" a 
pagina 13-21. 

I Unknown e Ilnterface 

Tutte le interfacce di Object Pascal discendono da un singolo antenato comune, 
Ilnterface. Non e necessario che le classi interfaccia di C++ utilizzino Ilnterface come 
classe di base, nel senso che una classe in stile VCL puo utilizzarle come classi di base 
aggiuntive, ma il codice VCL e CLX che opera con le interfacce presume che siano 
presenti i metodi di Ilnterface. 

Nella programmazione COM, tutte le interfacce discendono da IUnknown. II 
supporto COM nella VCL e basato su una definizione di IUnknown che mappa 
direttamente a Ilnterface. Cio significa che, in Object Pascal, IUnknown e Ilnterface sono 
identici. 

La definizione Object Pascal di IUnknown, tuttavia, non corrisponde alia definizione 
di IUnknown utilizzata in C++Builder. II file unknwn.h definisce IUnknown in modo 
tale da includere i seguenti tre metodi: 

virtual HRESULT STDCALL Querylnterf ace ( const GUID &guid, void ** ppv ) = 0; 
virtual ULONG STDCALL AddRefO = 0; 
virtual ULONG STDCALL Released = 0; 

Cio corrisponde alia definizione di IUnknown che e definite da Microsoft come parte 
delle specifiche COM. 

Per informazioni su IUnknown e sul suo utilizzo, vedere il Capitolo 38, "Panoramica 
sulle tecnologie COM" oppure consultare la documentazione Microsoft. 

A differenza di quanto accade in Object Pascal, la definizione di Ilnterface di 
C++Builder non e equivalente alia definizione di IUnknown. Ilnterface e invece un 
discendente di IUnknown che comprende un metodo aggiuntivo, Supports: 

template <typename T> 

HRESULT __stdcall Supports (DelphiInterface<T>& smartlntf) 
{ 

return Querylnterface ( uuidof (T) , 
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reinterpret_cast <void**>(static_cast<T**>(&smartIntf) ) ) ; 

} 

Supports consente di ottenere dall'oggetto che implementa Ilnterface una 
Delphilnterface per un'altra interfaccia supportata. Cosi, ad esempio, se si ha una 
Delphilnterface per un'interfaccia IMyFirstlnterface e l'oggetto che implementa 
implementa anche IMySecondlnterface (il cui tipo Delphilnterface e 
_di_IMySecondInterface), e possibile ottenere la Delphilnterface per la seconda 
interfaccia nel seguente modo: 

_di_IMySecondInterface MySecondlntf; 
MyFirstIntf->Supports (MySecondlntf) ; 

La VCL e la CLX utilizzano una mappatura di IUnknown in Object Pascal. Questa 
mappatura converte i tipi utilizzati nei metodi IUnknown in tipi Object Pascal e 
rinomina i metodi AddRefe Release in _AddRefe in _Release per indicare che essi non 
dovrebbero essere mai chiamati direttamente. (in Object Pascal, il compilatore genera 
automaticamente le chiamate necessarie a metodi IUnknown). Quando si mappano 
nuovamente in C++ i metodi di IUnknown (o di Ilnterface) supportati dagli oggetti 
della VCL o della CLX, cio produce le seguenti firme di metodi: 

virtual HRESULT __stdcall Query Interface (const QUID &IID, void *0bj); 
int __stdcall _AddRef (void) ; 
int stdcall _Release(void) ; 

Cio significa che gli oggetti VCL e CLX che supportano IUnknown o Ilnterface in 
Object Pascal non supportano le versioni di IUnknown e Ilnterface presenti in 
C++Builder. 

Creazione di classi che supportano IUnknown 

Molte classi nella VCL e nella CLX prevedono il supporto delle interfacce. Infatti, la 
classe di base per tutte le classi in stile VCL, TObject, ha un metodo Getlnterface che 
permette di ottenere una classe Delphilnterface per qualsiasi interfaccia che e 
supportata da un'istanza di un oggetto. TComponent e TInterfacedObject 
implementano entrambi i metodi Ilnterface (IUnknown). Pertanto, qualsiasi 
discendente creato di TComponent o di TInterfacedObject eredita automaticamente il 
supporto per i metodi comuni di tutte le interfacce di Object Pascal. In Object Pascal, 
quando si crea un discendente dell'una o dell'altra di queste classi, e possibile 
supportare una nuova interfaccia implementando solo quei metodi introdotti dalla 
nuova interfaccia, e facendo affidamento su un'implementazione predefinita per i 
metodi ereditati di Ilnterface. 

Sfortunatamente, poiche le firme dei metodi di IUnknown e di Ilnterface sono diverse 
tra C++Builder e le versioni utilizzate nelle classi VCL e CLX, le classi in stile VCL 
che vengono create non includono automaticamente il supporto per Ilnterface o per 
IUnknown, anche se sono derivate (direttamente o indirettamente) da TComponent o 
TInterfacedObject. Pertanto, per supportare qualsiasi interfaccia discendente da 
IUnknown o da Ilnterface che viene definita in C++, e sempre necessario aggiungere 
un'implementazione dei metodi di IUnknown. 

II modo piu semplice per implementare i metodi di IUnknown in una classe che 
discende da TComponent o TInterfacedObject consiste nello sfruttare il supporto nativo 
per IUnknown, nonostante le differenze nelle firme delle funzioni. + sufficiente 
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aggiungere le implementazioni per le versioni in C++ dei metodi di IUnknown, 
delegando alle versioni basate su Object Pascal ereditate. Ad esempio: 

virtual HRESULT __stdcall Query Interface (const GUID& IID, void "Obj ) 
return TInterfacedObject : :QueryInterface (IID, (void *)0bj); 

virtual ULONG __stdcall AddReff) 

return TInterfacedObject: :„AddRef () ; 

virtual ULONG __stdcall Released 

return TInterfacedObject: :_Release() ; 

Se si aggiungono a un discendente di TinterfacedObject le tre implementazioni di 
metodo appena viste, la classe ottiene il completo supporto per IUnknown o llnterface. 

Classi interfacciate e gestione del periodo di esistenza 

I metodi di IUnknown delle classi interfaccia presentano alcune problematiche per il 
modo in cui vengono allocati e liberati gli oggetti che implementano l'interfaccia. 
Quando IUnknown e implementato da un oggetto COM, l'oggetto utilizza i metodi di 
IUnknown per tenere traccia di quanti riferimenti alia sua interfaccia sono utilizzati. 
Quando il contatore dei riferimenti passa a zero, l'oggetto viene liberato 
automaticamente. TInterfacedObject implementa i metodi di IUnknown per eseguire 
una gestione analoga del periodo di esistenza. 

Questa interpretazione dei metodi di IUnknown, tuttavia, non e strettamente 
necessaria. L'implementazione predefinita dei metodi di IUnknown prevista da 
TComponent, ad esempio, ignora il conteggio dei riferimenti all'interfaccia, e pertanto 
il componente non viene liberato quando il numero dei riferimenti passa a zero. Cio e 
dovuto al fatto che TComponent fa affidamento sull'oggetto specificato mediante la 
sua proprieta Owner per liberare le risorse. 

Alcuni componenti utilizzano un ibrido di questi due modelli. Se la loro proprieta 
Owner e NULL, per la gestione del periodo di esistenza essi utilizzano il contatore dei 
riferimenti previsto dalla rispettiva interfaccia e vengono liberati quando quel 
contatore dei riferimenti arriva a zero. Nel caso abbiano un Owner, ignorano il 
contatore dei riferimenti e permettono al proprietario di liberarli. Si noti che per tali 
oggetti ibridi, come pure per qualsiasi altro oggetto che utilizza il contatore dei 
riferimenti per la gestione del periodo di esistenza, gli oggetti non vengono liberati 
automaticamente se l'applicazione crea l'oggetto ma non ottiene mai da esso 
un'interfaccia. 

Identita e istanziazione di un oggetto 



In C++ un'istanza di una classe e un oggetto reale. Questo puo essere manipolato 
direttamente, ma e accessibile anche indirettamente tramite un riferimento o un 
puntatore.Per esempio, data una classe CPP_class di C++ con un costruttore che non 
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richiede alcun argomento, le seguenti sono tutte variabili di istanze valide di quella 
classe: 

CPP_class by_value;// an object of type CPP_class 

CPP_class& ref = by_value;// a reference to the object by_value, above 

CPP_class* ptr = new CPP_class ( ) ; // a pointer to an object of type CPP_class 

Invece, in Object Pascal una variabile di tipo oggetto fa riferimento all'oggetto 
sempre in modo indiretto. La memoria viene allocata in modo dinamico per tutti gli 
oggetti. Per esempio, data una classe OP_class di Object Pascal 

ref: 0P_class; 

ref := 0P_class .Create; 

ref e un "riferimento" ad un oggetto di tipo OP_class. Tradotto in codice C++Builder, 
diventera 

0P_class* ref = new 0P_class; 

Distinzione tra i riferimenti in C++ e in Object Pascal 

Spesso la documentazione tratta una variabile di istanza di una classe Object Pascal 
come se fosse un riferimento, ma ne descrive il comportamento come se fosse un 
puntatore. Cio e dovuto al fatto che essa possiede le proprieta di entrambi. Un 
riferimento a oggetto di Object Pascal e simile ad un puntatore C++ con le seguenti 
eccezioni: 

• Un riferimento Object Pascal viene dereferenziato in modo implicito (nel qual caso 
funziona anche come un riferimento C++). 

• Un riferimento Object Pascal non ha un'aritmetica dei puntatori come 
un'operazione definita. 

Confrontando un riferimento Object Pascal con un riferimento C++, si scoprono 
analogie e differenze. In entrambi i linguaggi i riferimenti sono dereferenziati in 
modo implicito, tuttavia, 

• Un riferimento Object Pascal puo essere ricollegato, mentre un riferimento C++ 
no. 

• Un riferimento Object Pascal puo essere nil, mentre un riferimento C++ deve fare 
riferimento a un oggetto valido. 

Alcune delle decisioni di progettazione sottostanti la struttura VCL e CLX sono 
basate sull'uso di questo tipo di variabile di istanza. Un puntatore e il costrutto del 
linguaggio C++ piu vicino ad un riferimento Object Pascal. Ne consegue che in 
C++Builder quasi tutti gli identificatori di oggetti VCL vengono tradotti in puntatori 
C++. 

II tipo di parametro var di Object Pascal e una corrispondenza molto simile ad un 
riferimento C++. Per maggiori informazioni sui parametri var, vedere "Parametri 
var" a pagina 13-17. 

Copia di oggetti 

A differenza di C++, Object Pascal non integra nel compilatore il supporto per 
eseguire la copia di un oggetto. Qui di seguito viene spiegato l'impatto di questa 
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differenza sugli operatori di assegnazione e sui costruttori di copia per le classi in 
stile VCL. 

Operatori di assegnazione 

L'operatore di assegnazione (:=) di Object Pascal non e un operatore di assegnazione 
di classe (operatore=()). L'operatore di assegnazione copia il riferimento, non 
l'oggetto. Nel codice seguente, B e C si riferiscono alio stesso oggetto: 

B, C: TButton; 

B:= TButton. Create(ownerCtrl) ; 
C:= B; 

Questo esempio tradotto in C++Builder avrebbe il seguente codice: 

TButton *B = NULL; 
TButton *C = NULL; 
B = new TButton(ownerCtrl) ; 

C = B;// makes a copy of the pointer, not the object 

Le classi in stile VCL in C++Builder seguono le regole del linguaggio Object Pascal 
per gli operatori di assegnazione. Cio vuol dire che, nel codice seguente, le 
assegnazioni tra puntatori dereferenziati non sono valide in quanto esse tentano di 
copiare l'oggetto e non il puntatore: 

TVCLStyleClass *p = new TVCLStyleClass; 
TVCLStyleClass *q = new TVCLStyleClass; 
*P = *q;// not allowed for VCL style class objects 

Per le classi in stile VCL e sempre possibile usare la sintassi C++ per collegare un 
riferimento. Per esempio, il codice seguente e valido: 

TVCLStyleClass *ptr = new TVCLStyleClass; 
TVCLStyleClass &ref = *ptr;// OK for VCL style classes 

Anche se cio non equivale all'uso di un operatore di assegnazione, la sintassi e 
abbastanza simile perche valga la pena di riportarla in modo da poter effettuare un 
chiarimento e un confronto. 



Costruttori di copia 

Object Pascal non possiede costruttori di copia incorporati. Di conseguenza, in 
C++Builder le classi in stile VCL non hanno costruttori di copia incorporati. II codice 
dell'esempio seguente cerca di creare un puntatore TButton con un costruttore di 
copia: 

TButton *B = new TButton (ownerCtrl) ; 

TButton *C = new TButton (*B) ; // not allowed for VCL style class objects 

E opportuno non scrivere per le classi VCL e CLX codice che dipende da un 
costruttore di copia incorporato. Per creare una copia di un oggetto classe in stile 
VCL in C++Builder, si pud scrivere il codice per una funzione membro che copia 
l'oggetto. In alternativa, i discendenti della classe TPersistent della VCL e della CLX 
possono ridefinire il metodo Assign per copiare i dati da un oggetto all'altro. Cio 
normalmente viene fatto, per esempio, in classi grafiche come TBitmap e TIcon che 
contengono immagini di risorse. In conclusione, il modo di copiare un oggetto puo 
essere determinate dal programmatore (da colui che scrive il componente); ma 
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occorre prestare attenzione al rischio che qualcuno dei metodi di copia usati in C++ 
standard non sia disponibili per le classi stile VCL. 

Oggetti come argomenti di funzione 

Come e gia stato detto in precedenza, le variabili di istanza non sono indentiche in 
C++ e in Object Pascal. Queste differenze vanno tenute ben presenti quando si 
passano oggetti come argomenti alle funzioni. In C++, gli oggetti possono essere 
passati alle funzioni per valore, per riferimento e per puntatore. Quando in Object 
Pascal si passa per valore un oggetto a una funzione, occorre ricordare che l'oggetto e 
gia un riferimento a un oggetto. Di fatto, e il riferimento che viene passato per valore, 
non l'oggetto reale. Non esiste alcun equivalente Object Pascal per il passaggio di un 
oggetto reale per valore in C++. Gli oggetti in stile VCL passati alle funzioni seguono 
le regole dell'Object Pascal. 

Costruzione di oggetti per le classi VCLACLX di C++Builder 



C++ e Object Pascal costruiscono gli oggetti in modo differente. Questa sezione vuole 
essere una panoramica sull'argomento e presentare una descrizione di come 
C++Builder combina i due diversi approcci. 

Costruzione di oggetti in C++ 

In C++ standard la sequenza di costruzione e: classi base virtuali, classi base e infine 
classi derivate. La sintassi di C++ usa l'elenco di inizializzazione del costruttore per 
chiamare i costruttori della classe base. II tipo runtime dell'oggetto e quello della 
classe del costruttore attivo da chiamare. II dispatch del metodo virtuale segue il tipo 
runtime dell'oggetto e cambia conseguentemente durante la costruzione. 

Costruzione di oggetti in Object Pascal 

In Object Pascal viene chiamato solo il costruttore per le classi istanziate; tuttavia, 
viene allocata la memoria per le classi base. La costruzione di ogni classe base 
immediata viene effettuata chiamando inherited nel costruttore della classe derivata 
corrispondente. Per convenzione, le classi della VCL e della CLX usano inherited per 
chiamare i costruttori della classe base (non vuota). Occorre tenere presente, 
comunque, che questo non e un requisito del linguaggio. II tipo runtime dell'oggetto 
viene stabilito immediatamente uguale a quello della classe istanziata e non cambia 
quando vengono chiamati i costruttori della classe base. L'invio virtuale del metodo 
segue il tipo runtime dell'oggetto e pertanto non cambia durante la costruzione. 

Costruzione di oggetti in C++Builder 

Gli oggetti in stile VCL vengono costruiti come gli oggetti Object Pascal, ma usando 
la sintassi C++. Questo vuol dire che il metodo e l'ordine di chiamata dei costruttori 
della classe base segue la sintassi di C++ che usa l'elenco di inizializzazione per tutte 
le classi base non VCL e non CLX e il primo antenato VCL o CLX immediato. Questa 
classe base VCL o CLX e la prima classe che deve essere costruita. Opzionalmente, 
viene costruita una propria classe base usando inherited e seguendo il metodo 
Object Pascal. Pertanto, le classi base VCL e CLX vengono costruite nell'ordine 
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contrario a quello previsto in C++. Quindi, le classi base C++ vengono costruite 
completamente, dal piu lontano antenato alia classe derivata. II tipo runtime 
dell'oggetto e l'invio virtuale del metodo sono basati su Object Pascal. 

La Figura 13.1 illustra la costruzione di un'istanza di una classe in stile VCL, 
MyDerived, derivata da MyBase, che e un diretto discendente di TWinControl. 
MyDerived e MyBase vengono implementate in C++. TWinControl e una classe VCL 
implementata in Object Pascal. 

Figura 13.1 Sequenza di costruzione degli oggetti in stile VCL 

Inheritance Order of construction 



TObject 






TPersistent 






TComponent 




\ 


TControl 


✓ 




TWinControl 






MyBase 


✓ 




MyDerived 




TWinControl 
(constructor calls 
nherited 



TControl 
(constructor calls 
nherited 



TComponent 




boundary 





/ 


TPersistent 
(no constructor) 




/ 


TObject 
(empty constructor) 







MyBase 



MyDerived 



Si noti che, per un programmatore C++, la sequenza di costruzione potrebbe 
sembrare rovesciata, in quanto parte dall'antenato piu esterno per un TObject di vere 
classi VCL e CLX, quindi costruisce MyBase, e infine costruisce la classe derivata. 

TComponent non chiama inherited perche TPersistent non ha un costruttore. TObject 
ha un costruttore vuoto, quindi non viene chiamato. Se venissero chiamati questi 
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costruttori della classe, l'ordine seguirebbe il diagramma in cui queste classi 
appaiono in grigio. 

I modelli di costruzione dell'oggetto in C++, in Object Pascal e in C++Builder sono 
riportati nella Tabella 13.1: 



Tabella 13.1 Confronto dei modelli degli oggetti 



C++ 

Sequenza di costruzione 

Classi base virtuali, quindi 
classi base e infine la classe 
derivata. 



Object Pascal 



II costruttore della classe di cui 
e stata fatta un'istanza e il 
primo ed unico costruttore ad 
essere chiamato in modo 
automatico. Se vengono 
costruite altre classi, si parte 
dall'ultima per arrivare alia 
radice. 



Metodo di chiamata dei costruttori della classe base 



Automaticamente, dall'elenco 
di inizializzazione del 
costruttore. 



Opzionalmente, 
esplicitamente e in qualsiasi 
momenta nel corpo del 
costruttore della classe 
derivata, usando la parola 
chiave inherited. 



Tipo runtime dell'oggetto in fase di costruzione 

Cambia, riflettendo il tipo 
della classe attuale del 
costruttore. 



Fissato immediatamente 
uguale a quello della classe 
istanziata. 



Dispatch del metodo virtuale 

Cambia a seconda del tipo 
runtime dell'oggetto quando 
vengono chiamati i costruttori 
della classe base. 



Segue il tipo runtime 
dell'oggetto, che rimare 
identico in tutte le chiamate a 
qualsiasi costruttore della 
classe. 



C++Builder 



La classe base VCL o CLX piu 
recente, quindi la costruzione 
segue il modello Object Pascal, 
e prosegue con il modello C++ 
(con Tunica differenza che le 
classi basi virtuali non sono 
consentite). 



Automaticamente dall'elenco 
di inizializzazione del 
costruttore attraverso 
l'antenato piu recente che e un 
costruttore della classe base 
VCL e CLX. Quindi secondo il 
metodo Object Pascal, 
chiamando i costruttori con 
inherited. 



Fissato immediatamente 
uguale a quello della classe 
istanziata. 



Segue il tipo runtime 
dell'oggetto, che rimare 
identico in tutte le chiamate a 
qualsiasi costruttore della 
classe. 



L'importanza di queste difference viene descritta nella sezione seguente. 



Chiamata dei metodi virtuali nei costruttori della classe base 



I metodi virtuali richiamati dal corpo dei costruttori della classe base VCL o CLX, 
cioe, delle classi implementate in Object Pascal, vengono organizzati come in C++, 
secondo il tipo runtime dell'oggetto. Poiche C++Builder abbina immediatamente il 
modello Object Pascal di impostazione del tipo runtime di un oggetto con il modello 
C++ di costruzione delle classi base prima che la classe derivata venga costruita, 
chiamando i metodi virtuali dai costruttori della classe base per le classi stile VCL, si 
possono verificare effetti collaterali indesiderati. L'incidenza di cio viene descritta 
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sotto, e poi viene illustrata in un esempio di una classe istanziata che viene derivata 
da almeno una classe base. In questa trattazione la classe istanziata viene considerata 
la classe derivata. 

Modello Object Pascal 

In Object Pascal i programmatori possono usare la parola chiave inherited, che 
fornisce la flessibilita necessaria per chiamare i costruttori della classe base da 
qualsiasi punto del corpo di un costruttore della classe derivata. Conseguentemente, 
se la classe derivata ridefinisce dei metodi virtuali che dipendono dall'impostazione 
dell'oggetto o dall'inizializzazione dei membri dati, cio puo succedere prima che 
vengano chiamati il costruttore della classe base e i metodi virtuali. 

Modello C++ 

La sintassi C++ non ha la parola chiave inherited per chiamare il costruttore della 
classe base in qualsiasi momento durante la costruzione della classe derivata. Per il 
modello C++ l'uso di inherited non e necessario perche il tipo runtime dell'oggetto e 
quello della classe corrente che deve essere costruita, non quello della classe derivata. 
Percio, i metodi virtuali chiamati sono quelli della classe attiva, non quelli della classe 
derivata. Conseguentemente, non e necessario inizializzare i membri dati o 
impostare l'oggetto della classe derivata prima che vengano chiamati questi metodi. 

Modello C++Builder 

In C++Builder gli oggetti in stile VCL hanno il tipo runtime della classe derivata in 
tutte le chiamate ai costruttori della classe base. Percio, se il costruttore della classe 
base chiama un metodo virtuale, il metodo della classe derivata viene chiamato se la 
classe derivata lo ridefinisce. Se questo metodo virtuale dipende da qualcosa 
nell'elenco di inizializzazione o nel corpo del costruttore della classe derivata, il 
metodo viene chiamato prima che cio accada. Per esempio, CreateParams e una 
funzione membro virtuale che viene chiamata indirettamente nel costruttore di 
TWinControl. Se si deriva una classe da TWinControl e si ridefinisce CreateParams in 
modo che dipenda da qualcosa nel costruttore, questo codice viene elaborato dopo 
che viene chiamata CreateParams. Questa situazione vale per qualsiasi classe derivata 
di una base. Si consideri una classe C derivata da B, che e derivata da A. Creando 
un'istanza di C, A chiamerebbe anche il metodo ridefinito di B, se B ridefinisce il 
metodo e C no. 

Si deve tener presente che i metodi virtuali come CreateParams ovviamente non 
vengono chiamati nei costruttori, ma vengono chiamati indirettamente. 

Esempio: chiamata dei metodi virtuali 

L'esempio seguente confronta le classi C++ e quelle in stile VCL che hanno sostituito 
i metodi virtuali. Questo esempio illustra come vengono risolte in entrambi i casi le 
chiamate a quei metodi virtuali dai costruttori della classe base. MyBase e MyDerived 
sono classi standard di C++. MyVCLBase e MyVCLDerived sono classi in stile VCL 
derivate da TObject. II metodo virtuale what_am_I() viene ridefinito in entrambe le 
classi derivate, ma viene chiamato solo nei costruttori della classe base, non nei 
costruttori della classe derivata. 
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♦include <sysutils .hpp> 
♦include <iostream.h> 
// non-VCL style classes 
class MyBase { 
public : 

MyBase () { what_am_I() ; } 

virtual void what_am_l() { cout << "I am a base" « endl; } 

}; 

class MyDerived : public MyBase { 
public : 

virtual void what_am_l() { cout « "I am a derived" « endl; } 

}; 

// VCL style classes 

class MyVCLBase : public TObject { 

public : 

__fastcall MyVCLBase () { what_am_l(); } 

virtual void __fastcall what_am_l() { cout « "I am a base" « endl; } 

}; 

class MyVCLDerived : public MyVCLBase { 
public : 

virtual void __fastcall what_am_l() { cout « "I am a derived" « endl; } 

}; 

int main (void) 

{ 

MyDerived d;// instantiation of the C++ class 

MyVCLDerived *pvd = new MyVCLDerived;// instantiation of the VCL style class 
return 0; 

} 

L'output di questo esempio e 

I am a base 
I am a derived 

a causa della differenza nei tipi runtime di MyDerived e MyVCLDerived durante le 
chiamate ai rispettivi costruttori della classe base. 

Inizializzazione del costruttore dei membri dati per le funzioni virtuali 

Poiche i membri dati possono essere usati in funzioni virtuali, e importante capire 
quando e come vengono inizializzati. In Object Pascal tutti i dati non inizializzati 
vengono inizializzati a zero. Questo vale, per esempio, per le classi base i cui 
costruttori non vengono chiamati con inherited. In C++ standard non c'e alcuna 
garanzia sul valore dei membri dati non inizializzati. I seguenti tipi di membri dati di 
classe devono essere inizializzati nell'elenco di inizializzazione del costruttore della 
classe: 

• riferimenti 

• membri dati senza costruttori predefiniti 

Cio nonostante, il valore di questi membri dati, o di quelli inizializzati nel corpo del 
costruttore, non e definito quando vengono chiamati i costruttori della classe base. In 
C++Builder la memoria per le classi in stile VCL e inizializzata a zero. 
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Tecnicamente, e la memoria della classe VCL o CLX che e zero, ovvero sono i bit a 
zero, mentre i valori non sono in realta definiti. Per esempio, un riferimento e zero. 

Una funzione virtuale che fa affidamento sul valore delle variabili membro 
inizializzate nel corpo del costruttore o nell'elenco di inizializzazione puo 
comportarsi come se le variabili fossero inizializzate a zero. Questo si verifica perche 
il costruttore della classe base viene chiamato prima che l'elenco di inizializzazione 
venga elaborato o che il corpo del costruttore venga immesso. L'esempio seguente 
illustra cio che succede: 

♦include <sysutils.hpp> 

class Base : public TObject { 
public : 

__fastcall Basel) { initO ; } 
virtual void __fastcall initO { } 

}; 

class Derived : public Base { 
public : 

Derived(int nz) : not_zero (nz ) { } 
virtual void __fastcall initO 
{ 

if (not_zero == 0) 

throw Exception ( "not_zero is zero!"); 

} 

private : 

int not_zero; 

}; 

int main (void) 

{ 

Derived *d42 = new Derived(42) ; 
return 0; 

} 

Questo esempio presenta un'eccezione nel costruttore di Base. Poiche Base viene 
costruita prima di Derived, not_zero, non e stata ancora inizializzata con il valore di 42 
passato al costruttore. Si tenga presente che non e possibile inizializzare i membri 
dati della classe in stile VCL prima che vengano chiamati i costruttori della sua classe 
base. 

Distruzione di oggetti 



Due meccanismi, riguardanti la distruzione degli oggetti, funzionano 
differentemente in C++ e in Object Pascal. Questi sono: 

• distruttori chiamati a causa delle eccezioni presentate dai costruttori 

• i metodi virtuali chiamati dai distruttori 

Le classi in stile VCL abbinano i metodi di questi due linguaggi. Gli aspetti vengono 
discussi qui di seguito. 
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Eccezioni sollevate dai costruttori 

Se si verifica un'eccezione durante la costruzione dell'oggetto, i distruttori vengono 
chiamati in modo differente in C++ e in Object Pascal. Si prenda come esempio una 
classe C, derivata da una classe B, che e derivata da una classe A: 



class 


A 


{ 




II 

}; 


body 


class 


B: public A 


{ 

// 

}; 


body 


class 


C: public B 


{ 

// 


body 



}; 

Supponendo che si sia verificata un'eccezione nel costruttore della classe B durante la 
costruzione di un'istanza di C, questi sarebbero i risultati in C++, in Object Pascal e in 
classi in stile VCL: 

• In C++ prima vengono chiamati i distruttori per tutti i membri dati dell'oggetto 
completamente costruiti di B, quindi viene chiamato il distruttore di A, e 
successivamente vengono chiamati i distruttori per tutti i membri dati dell'oggetto 
completamente costruiti di A. Comunque, i distruttori per B e C non vengono 
chiamati. 

• In Object Pascal solo il distruttore della classe istanziata viene chiamato 
automaticamente. Questo e il distruttore per C. Come avviene con i costruttori, e 
esclusivamente responsabilita del programmatore chiamare inherited nei 
distruttori. In questo esempio, se si suppone che tutti i distruttori chiamano 
inherited, allora i distruttori per C, B e A vengono chiamati in questo ordine. 
Inoltre, indipendentemente dal fatto che inherited sia gia stata o meno chiamata 
nel costruttore di B prima che si verificasse l'eccezione, il distruttore di A viene 
chiamato perche inherited e stato chiamato nel distruttore di B. La chiamata al 
distruttore per A e indipendente dal fatto che il suo costruttore sia stato 
effettivamente chiamato. Inoltre, fattore piu importante, poiche di solito i 
costruttori chiamano immediatamente inherited, il distruttore per C viene 
chiamato indipendentemente dal fatto che il corpo del suo costruttore sia stato o 
no completamente eseguito. 

• Nelle classi in stile VCL le basi della VCL o della CLX (implementate in Object 
Pascal) seguono il metodo Object Pascal di chiamata dei distruttori. Le classi 
derivate (implementate in C++) non seguono esattamente nessuno dei metodi del 
linguaggio. Succede invece che vengono chiamati tutti i distruttori; ma i corpi di 
quelli che non saranno stati chiamati secondo le regole del linguaggio C++, non 
vengono immessi. 

Le classi implementate in Object Pascal, pertanto, forniscono un'opportunita per 
elaborare qualsiasi codice di cleanup scritto nel corpo del distruttore. Cio e vero 
anche per il codice che libera memoria per i sotto-oggetti (membri dati che sono 
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oggetti) che vengono costruiti prima che si verifichi un'eccezione del costruttore. Si 
deve tenere presente che, per le classi in stile VCL, il codice di cleanup puo non 
essere elaborato per la classe istanziata o per le sue basi implementate con C++, 
anche se vengono chiamati i distruttori. 

Per maggiori informazioni sulla gestione delle eccezioni in C++Builder, consultare 
"Gestione delle eccezioni VCL/CLX" a pagina 12-15. 

Metodi virtuali chiamati dai distruttori 

L'invio dei metodi virtuali nei distruttori segue lo stesso modello def inito per i 
costruttori. Questo significa che per le classi in stile VCL, la classe derivata viene 
distrutta per prima, ma il tipo runtime dell'oggetto rimane quello della classe 
derivata in tutte le successive chiamate ai distruttori della classe base. Pertanto, se i 
metodi virtuali vengono chiamati nei distruttori della classe base VCL o CLx, c'e il 
rischio che l'invio riguardi una classe che e gia stata distrutta. 

AfterConstruction e Before Destruction 



TObject propone due metodi virtuali, BeforeDestruction e AfterConstruction, che 
consentono ai programmatori di scrivere del codice che viene elaborato 
rispettivamente prima e dopo la distruzione e la creazione degli oggetti. 
AfterConstruction viene chiamato dopo la chiamata dell'ultimo costruttore. 
BeforeDestruction viene chiamato prima che venga chiamato il primo distruttore. 
Questi metodi sono pubblici e vengono chiamati automaticamente. 

Funzioni virtuali di classe 



Object Pascal ha il concetto di funzione virtuale di classe.L'analogo C++ sarebbe una 
funzione virtuale statica, se fosse possibile; ma C++ non ha alcun corrispondente di 
questo tipo di funzione. Queste funzioni vengono chiamate con sicurezza all'interno 
della VCL e della CLX. Tuttavia, in C++Builder non verra mai chiamata una funzione 
di questo tipo. + possibile identificare queste funzioni nei file header in quanto sono 
precedute dal seguente commento: 

/* virtual class method */ 

Supporto per i tipi di dati Object Pascal e per le strutture del 
linguaggio 

Per supportare la VCL e la CLX, C++Builder implementa, traduce o mette comunque 
in relazione la maggior parte dei tipi di dati, dei costrutti e delle strutture del 
linguaggio Object Pascal con quelli del linguaggio C++. Cio viene realizzato nei 
seguenti modi: 

• Typedefs per i tipi C++ nativi 

• Classes, strutture e modelli di classe 

• Equivalenti del linguaggio C++ 
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• Macro 

• Parole chiave che sono estensioni del linguaggio ANSI standard 

Non tutti gli aspetti del linguaggio Object Pascal coincidono perfettamente con quelli 
del C++. A volte, l'uso di queste parti del linguaggio puo far si che l'applicazione 
abbia dei comportamenti inattesi. Ad esempio: 

• Alcuni tipi esistono in Object Pascal e in C++, ma vengono definiti in modo 
diverse Essi possono richiedere una particolare attenzione quando il codice viene 
condiviso dai due linguaggi. 

• Alcune estensioni sono state aggiunte a Object Pascal con lo scopo di supportare 
C++Builder. Occasionalmente esse possono avere una notevole incidenza a livello 
di interoperativita. 

• I tipi e i costrutti del linguaggio Object Pascal che hanno alcun corrispondente nel 
linguaggio C++ saranno evitati in C++Builder quando il codice viene condiviso tra 
questi linguaggi. 

La sezione successiva presenta un riepilogo dei modi in cui C++Builder implementa 
il linguaggio Object Pascal, e alcuni suggerimenti su quando occorre usare una certa 
prudenza. 

Typedef 



La maggior parte dei tipi di dati intrinseci Object Pascal viene implementata in 
C++Builder usando un typedef per un tipo C++ nativo. Questi si trovano in 
sysmach. Ogni qual volta e possibile, e opportuno usare il tipo C++ nativo, anziche il 
tipo Object Pascal. 

Classi che supportano il linguaggio Object Pascal 



Alcuni tipi di dati e costrutti del linguaggio Object Pascal che non hanno un 
equivalente incorporato in C++ vengono implementati come classi o strutture. I 
modelli di classe vengono usati anche per implementare i tipi di dati e i costrutti del 
linguaggio Object Pascal, come set, da cui puo essere dichiarato uno specifico tipo. Le 
relative dichiarazioni si trovano nei seguenti file header: 

• dstring.h 

• wstring.h 

• sysclass.h 

• syscomp.h 

• syscurr.h 

• sysdyn.h 

• sysopen.h 

• sysseth 

• systdate.h 

• systobj.h 

• systvar.h 

• sysvarLh 



13-16 Guida alia programmazione 



Supporto per i tipi d i dati Object Pascal e per le strutture del linguaggio 

Le classi implementate in questi file header sono state create per supportare i tipi 
nativi usati nelle routine Object Pascal. Esse sono destinate ad essere usate quando 
queste routine vengono chiamate nel codice basato su VCL o CLX. 

Equivalenti del linguaggio C++ presenti nel linguaggio Object Pascal 



I parametri var e untyped di Object Pascal non sono nativi di C++. Entrambi hanno 
degli equivalenti nel linguaggio C++ che vengono usati in C++Builder. 

Parametri var 

C++ e Object Pascal condividono la logica del "passaggio per riferimento". Questi 
sono argomenti modificabili. In Object Pascal vengono chiamati parametri var. La 
sintassi per le funzioni che richiedono un parametro var e 

procedure myFuncfvar x : Integer); 

In C++ questi tipi di parametro devono essere passati per riferimento: 

void rnyFunc(int& x) ; 

I riferimenti e i puntatori di C++ possono essere usati per modificare l'oggetto. 
Tuttavia, un riferimento e il corrispondente piu vicino ad un parametro var in 
quanto, a differenza di un puntatore, un riferimento non puo essere rebound e un 
parametro var non puo essere assegnato una seconda volta; anche se e possibile 
cambiare il valore di cio a cui fa riferimento. 

Parametri senza tipo 

Object Pascal consente l'uso di parametri di tipo non specificato. Questi parametri 
vengono passati alle funzioni senza alcun tipo definito. La funzione ricevente deve 
ricondurre il parametro ad un tipo noto prima di usarlo. C++Builder interpreta i 
parametri di tipo non specificato come puntatori a vuoto (void *). La funzione 
ricevente deve ricondurre il puntatore vuoto ad un puntatore del tipo desiderato. 
Questo e un esempio: 

int myfunc (void* MyName) 

{ 

// Cast the pointer to the correct type; then dereference it. 
int* pi = static_cast <int*> (MyName) ; 
return 1 + *pi; 

} 

Open array 



Object Pascal ha un costrutto "open array" che permette di passare a una funzione un 
array di dimensioni non specificate. Mentre in C++ non esiste alcun supporto diretto 
per questo tipo, una funzione Object Pascal che ha un parametro array aperto puo 
essere chiamata passando esplicitamente il puntatore al primo elemento di un array, 
e il valore all'ultimo indice (il numero di elementi dell'array meno uno). Per esempio, 
la funzione Mean in math.hpp ha questa dichiarazione in Object Pascal: 
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function Mean(Data: array of Double): Extended; 

La dichiarazione in C++ e 

Extended __fastcall Meanfconst double * Data, const int Data_Size) ; 

II codice seguente illustra la chiamata della funzione Mean da C++: 

double d[] = { 3.1, 4.4, 5.6 }; 

// explicitly specifying last index 
long double x = Mean(d, 2); 

// better: use sizeof to ensure that the correct value is passed 
long double y = Meanfd, (sizeof (d) / sizeof (d[0] ) ) - 1); 

// use macro in sysopen.h 
long double z = Mean(d, ARRAYSIZE (d) - 1); 

In casi simili all'esempio sopra riportato, ma dove la funzione Object Pascal aspetta 
un parametro var, i parametri di dichiarazione di funzione C++ non saranno const. 

Calcolo del numero di elementi 

Quando si usa sizeofO, la macro ARRAYSIZE o la macro EXISTINGARRAY per 
calcolare il numero di elementi di un array, occorre prestare attenzione a non usare 
invece un puntatore all'array. Passare invece il nome dello stesso array: 

double d[] = { 3.1, 4.4, 5.6 }; 

int n = ARRAYSIZE (d) ; // sizeof (d) /sizeof (d[0] ) => 24/8 => 3 
double *pd = d; 

int m = ARRAYSIZE (pd) ; // sizeof (pd) /sizeof (pd[0] ) => 4/8 => => Error! 

Prendere il "sizeof" di un array non equivale a prendere il "sizeof" di un puntatore. 
Per esempio, data la seguente dichiarazione, 

double d[3]; 
double *p = d; 

che assume le dimensioni dell'array come mostrato 

sizeof (d) /sizeof d[0] 
non equivale a calcolare le dimensioni del puntatore: 
sizeof (p) /sizeof (p[0] ) 

Questo esempio e quelli seguenti usano la macro ARRAYSIZE anziche l'operatore 
sizeofi). Per maggiori informazioni sulla macro ARRAYSIZE, consultare la Guida in 
linea. 

Array temporanei 

Object Pascal fornisce il supporto per il passaggio di array aperti temporanei senza 
nome alle funzioni. In C++ non esiste alcuna sintassi che svolga questa operazione. 
Tuttavia, poiche le definizioni di variabili possono essere mischiate con altre 
istruzioni, un modo per risolvere il problema e quello di fornire semplicemente la 
variabile con un nome. 

Object Pascal: 
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Result := Mean( [3.1, 4.4, 5.6]) ; 

C++, usando un array "temporaneo" con nome: 

double d[] = { 3.1, 4.4, 5.6 }; 
return Mean(d, ARRAYSIZE (d) - 1); 

Per restringere il campo d'azione dell'array "temporaneo" con nome ed evitare 
conflitti con altre variabili locali, e consigliabile aprire un nuovo campo d'azione: 

long double x; 

{ 

double d[] = { 4.4, 333.1, 0.0 }; 

x = Meanfd, ARRAYSIZE (d) - 1); 

} 

Per un'altra soluzione, vedere "Macro OPENARRAY" a pagina 13-19. 

Array of const 

Object Pascal supporta un costrutto del linguaggio chiamato array of const. Questo 
tipo di argomento equivale ad acquisire un open array di TVarRec per valore. 

II seguente e un segmento di codice Object Pascal dichiarato per accettare un array of 
const: 

function Format (const Format: string; Args: array of const): string; 

In C++ il prototipo e 

AnsiString fastcall Format (const AnsiString Format, 

TVarRec const *Args, const int Args_Size) ; 

La funzione viene chiamata proprio come qualsiasi altra funzione che acquisisce un 
open array: 

void show_error (int error_code, AnsiString const &error_msg) 
{ 

TVarRec v[] = { error_code, error_msg } ; 
ShowMessage(Format("%d: is", v, ARRAYSIZE (v) - 1)); 

} 

Macro OPENARRAY 

La macro OPENARRAY definita in sysopen.h pud essere usata come alternativa ad 
una variabile con nome per passare un open array temporaneo ad una funzione che 
acquisisce un open array per valore. L'uso della macro assume questo formato 

OPENARRAY ( T , (valuel, value2, value3)) // up to 19 values 

dove T e il tipo open array da costruire e i parametri value sono utilizati per 
compilare l'array. Le parentesi per racchiudere gli argomenti dei valori sono 
necessarie. Ad esempio: 

void show_error (int error_code, AnsiString const &error_msg) 
{ 

ShowMessage (Format ( "%d: %s", OPENARRAY (TVarRec, (error_code, error_msg) ) ) ) ; 

} 
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Con la macro OPENARRAY possono essere passati fino a 19 valori. Se fosse 
necessario un array piu grande, occorrerebbe definire una variabile esplicita. Inoltre, 
usando la questa macro, si paga un ulteriore piccolo costo in fase di esecuzione, 
dovuto sia alia spazio richiesto per l'allocazione dell'array sottostante sia alia 
ulteriore copia di ciascun valore. 

Macro EXISTINGARRAY 

La macro EXISTINGARRAY definita in sysopen.h pud essere usata per passare un 
array esistente al posto di un open array. L'uso della macro assume questo formato 

long double Mean (const double *Data, const int Data_Size) ; 

double d[] = { 3.1, 3.14159, 2.17128 }; 
Mean (EXISTINGARRAY (d) ) ; 

La sezione "Calcolo del numero di elementi" a pagina 13-18 vale anche per la macro 
EXISTINGARRAY. 



Funzioni C++ che accettano argomenti di tipo open array 

Quando si scrive una funzione C++ a cui verra passato un array aperto da Object 
Pascal, e importante conservare esplicitamente la semantica del "passaggio per 
valore". In particolare, se la dichiarazione per la funzione corrisponde al "passaggio 
per valore", bisogna accertarsi di aver copiato esplicitamente tutti gli elementi prima 
di modificarli. In Object Pascal un array aperto e un tipo incorporato e puo essere 
passato per valore. In C++ il tipo array aperto viene implementato usando un 
puntatore, il quale modifica l'array originale, a meno che non ne venga fatta una 
copia locale. 



Tipi definiti in altro modo 



I tipi che in Object Pascal e C++ vengono definiti in modo diverso normalmente non 
sono causa di preoccupazioni. I rari casi in cui sono problematici risultano 
difficilmente individuabili. Per tale motivo, questi tipi vengono trattati in questa 
sezione. 



Tipi di dati booleani 

In Object Pascal il valore True per i tipi di dati ByteBool, WordBool e LongBool viene 
rappresentato con -1. False viene rappresentato con 0. 

II tipo di dati Boolean rimane costante (true = 1, false = 0)). 

Mentre il tipo bool di C++ converte correttamente questi tipi di Object Pascal, 
nascono problemi quando vengono condivise una funzione WinAPI o una qualsiasi 
altra funzione che usa un tipo BOOL di Windows rappresentato con 1. Se viene 
passato un valore ad un parametro di tipo BOOL, esso vale -1 in Object Pascal e 1 in 
C++. Pertanto, se tra questi due linguaggi viene condiviso del codice, qualsiasi 
confronto dei due identificatori puo risultare errato, a meno che non siano entrambi 
(False, false). Per aggirare l'ostacolo, si puo usare il seguente metodo di confronto: 

!A == !B; 
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La Tabella 13.2 mostra i risultati dell'uso di questo metodo di confronto 
dell'uguaglianza: 

Tabella 13.2 Confronto dell'uguaglianza !A == !B di variabili BOOL 



Object Pascal 


C++ 


!A == !B 


(False) 


(false) 


!0 == !0 (TRUE) 


(False) 


1 (true) 


!0 == !1 (FALSE) 


-1 (True) 


(false) 


!-l == !0 (FALSE) 


-1 (True) 


1 (true) 


!-l == !l (TRUE) 



Con questo metodo di confronto qualunque serie di valori sara calcolata 
correttamente. 



Tipi di dati char 

II tipo char in C++ e con segno, mentre in Object Pascal e senza segno. + molto raro 
che si verifichi una situazione in cui questa differenza potrebbe diventare un 
problema quando viene condiviso del codice. 

Interfacce Delphi 



I compilatore Object Pascal gestisce automaticamente molti dettagli durante le 
attivita con le interfacce. Incrementa automaticamente il contatore dei riferimenti di 
un'interfaccia quando il codice dell'applicazione acquisisce un puntatore 
all'interfaccia e decrementa tale contatore quando l'interfaccia esce dal campo di 
validita. 

In C++Builder, la classe modello Delphilnterface fornisce alle classi interfaccia di C++ 
solo una parte di tali automatismi. Per le proprieta e i metodi nella VCL e nella CLX 
che utilizzano i tipi interfaccia in Object Pascal, i wrapper di C++ utilizzano una 
Delphilnterface che e costruita utilizzando la classe interfaccia sottostante. 

II costruttore Delphilnterface, il costruttore copia, l'operatore di assegnazione e il 
distruttore incrementano o decrementano all'occorrenza il contatore dei riferimenti. 
Tuttavia, Delphilnterface non e cosi conveniente quanto il supporto offerto dal 
compilatore per le interfacce in Object Pascal. Altri operatori che forniscono l'accesso 
al puntatore all'interfaccia sottostante non gestiscono il conteggio dei riferimenti 
perche la classe non pud sempre dire quando e opportuno farlo. Potrebbe essere 
necessario chiamare esplicitamente AddRefo Release per essere certi che il conteggio 
dei riferimenti sia corretto. 

Stringhe di risorse 



Se nel codice e presente una unit Pascal che usa stringhe di risorse, il compilatore 
Pascal (DCC32) genera una variabile globale e una corrispondente macro del 
preprocessore per ciascuna stringa di risorse quando genera il file header. Le macro 
vengono usate per caricare automaticamente le stringhe di risorse, e sono destinate 
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ad essere usate nel codice C++ dovunque si fa riferimento alia stringa di risorse. Per 
esempio, la sezione resourcestring nel codice Object Pascal puo contenere 

unit borrowed; 

interface 

resourcestring 

Warning = 'Be careful when accessing string resources.'; 
implementation 
begin 
end. 

II codice corrispondente generato dal compilatore Pascal per C++Builder sara 

extern PACKAGE System: :Resource Resourcestring _ Warning; 

♦define BorrowecLWarning System: :LoadResourceString(S;Borrowed: :_Warning) 

Questo consente di usare le stringhe di risorse Object Pascal esportate senza dover 
chiamare in modo esplicito LoadResourceString. 

Parametri predefiniti 

La versione piu recente del compilatore Pascal accetta parametri predefiniti per i 
costruttori per compatibilita con C++. A differenza di C++, i costruttori Object Pascal 
possono pero avere stesso numero e gli stessi tipi di parametri, poiche ad essi viene 
attribuito un nome univoco. In tali casi nei costruttori Object Pascal vengono usati 
parametri fittizi per distinguerli quando vengono generati i file header di C++. Per 
esempio, per una classe chiamata TInCompatible, i costruttori Object Pascal 
potrebbero essere 

constructor Create (AOwner: TComponent); 
constructor CreateNew (AOwner: TComponent); 

che porterebbero, senza parametri predefiniti, al seguente codice ambiguo in C++ per 
entrambi i costruttori: 

__fastcall TInCompatible (Classes : :TComponent* Owner);// C++ version of the Pascal Create 
constructor 

__fastcall TInCompatible (Classes : :TComponent* Owner);// C++ version of the Pascal CreateNew 
constructor 

Tuttavia, usando parametri predefiniti, per una classe chiamata TCompatible, i 
costruttori Object Pascal sono 

constructor Create (AOwner: TComponent); 

constructor CreateNew (AOwner: TComponent; Dummy: Integer = 0); 

Essi portano al seguente codice non ambiguo in C++Builder: 

__fastcall TCompatible (Classes : :TComponent* Owner);// C++ version of the Pascal Create 
constructor 

__fastcall TCompatible (Classes: :TComponent* Owner, int Dummy);// C++ version of the Pascal 
CreateNew constructor 

L-v/jw II problema principale con i parametri predefiniti e che DCC32 rimuove il valore 
C_J predefinito del parametro predefinito. Un errore in tale operazione puo generare 
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ambiguita qualora non ci siano parametri predefiniti. Bisogna tenerne conto quando 
si usano classi VCL o CLX oppure componenti di produttori terzi. 

Informazioni di tipo runtime 

Object Pascal ha costrutti di linguaggio che hanno a che fare con RTTI. Alcuni hanno 
equivalenti in C++. Essi vengono elencati nella Tabella 13.3: 

Tabella 13.3 Esempi di correlazioni RTTI da Object Pascal a C++ 
RTTI Object Pascal RTTI C++ 

if Sender is TButton... if (dynamic_cast <TButton*> (Sender) 

// dynamic_cast restituisce NULL in caso di errore. 

b := Sender as TButton; TButton& ref_b = dynamic_cast <TButton&> (*Sender) 

(* genera un'eccezione in caso di / / genera un'eccezione in caso di errore. 
errore *) 

ShowMessage(Sender.ClassName); ShowMessage(typeid(*Sender).name()); 

Nella Tabella 13.3, ClassName e un metodo TObject che restituisce una stringa 
contenente il nome del tipo attuale dell'oggetto, indipendentemente dal tipo di 
variabile dichiarata. Gli altri metodi RTTI introdotti in TObject non hanno equivalenti 
in C++. Essi sono tutti pubblici e sono elencati qui di seguito: 

• Classlnfo restituisce un puntatore alia tabella contenente le informazioni di tipo 
runtime (RTTI) del tipo di oggetto. 

• ClassNamels determina se un oggetto e di uno specifico tipo. 

• ClassParent restituisce il tipo dell'antenato diretto della classe. Nel caso di TObject 
ClassParent restituisce nil perche TObject non non ha alcun parente. Viene usato 
dagli operatori is e as, e dal metodo InheritsFrom. 

• ClassType determina dinamicamente il tipo attuale di un oggetto. Viene usato 
internamente dagli operatori is e as di Object Pascal. 

• FieldAddress usa RTTI per ottenere l'indirizzo di un campo pubblicato. Viene usato 
internamente dal sistema steaming. 

• InheritsFrom determina la relazione tra due oggetti. Viene usato internamente 
dagli operatori is e as di Object Pascal. 

• MethodAddress usa RTTI per trovare l'indirizzo di un metodo. Viene usato 
internamente dal sistema steaming. 

Alcuni di questi metodi di TObject sono destinati principalmente all'uso inferno da 
parte del compilatore o del sistema streaming. Per maggiori informazioni, consultare 
la Guida in linea. 
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Tipi non mappati 



Tipi real a 6 byte 

II vecchio formato a virgola mobile a 6 byte di Object Pascal ora viene chiamato 
Real48. II vecchio tipo Real ora e un double. C++ non ha un equivalente per il tipo 
Real48. Conseguentemente, non si deve usare del codice Object Pascal che includa 
questo tipo con il codice C++. Altrimenti, il generatore del file header generera un 
messaggio. 

Arrays come tipi restituiti da funzioni 

In Object Pascal una funzione puo richiedere come argomento, o restituire come tipo, 
un array. Per esempio, la sintassi per una funzione GetLine che restituisce un array di 
80 caratteri e 

type 

Line_Data = array [0.. 79] of char; 
function GetLine: Line_Data; 

C++ non ha un equivalente di questa funzione. In C++ gli array non sono consentiti 
come tipi restituiti da funzioni. E tantomeno C++ accetta array come tipo di 
argomento di una funzione. 

E bene tenere presente che, sebbene la VCL e la CLX non abbiano alcuna proprieta 
che sia un array, il linguaggio Object Pascal lo consente. Dal momento che le 
proprieta possono usare i metodi di lettura e di scrittura Get e Set, che richiedono e 
restituiscono valori del tipo della proprieta, in C++Builder non e possibile avere una 
proprieta di tipo array. 

Le proprieta array, che sono valide anche in Object Pascal, non sono un problema in 
C++ perche il metodo Get prende un valore di indice come parametro, mentre il 
metodo Set restituisce un oggetto del tipo contenuto dall'array. Per maggiori 
informazioni sulle proprieta array, consultare "Creazione di proprieta array" a 
pagina 47-8. 

Estensioni di parole chiave 



Questa sezione descrive le estensioni di parole chiave conformi con lo standard 
ANSI, implementate in C++Builder per supportare la VCL e la CLX. Per un elenco 
completo delle parole chiave e delle relative estensioni in C++Builder, consultare la 
Guida in linea. 

_classid 

L'operatore classid viene usato dal compilatore per generare un puntatore a vtable 

per il classname specificate Questo operatore viene usato per ottenere la classe meta 
da una classe. 

Sintassi __classid (classname) 

Per esempio, classid viene usato per la registrazione di editor di proprieta, di 

componenti e di classi, e con il metodo InheritsFrom di TObject. II codice seguente 
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illustra l'uso di classid per la creazione di un nuovo componente derivato da 

TWinControI: 

namespace Ywndctrl 
{ 

void __fastcall PACKAGE Register)) 
{ 

TComponentClass classes [1] = {__classid (MyWndCtrl) } ; 
RegisterComponents ( "Additional" , classes, 0); 



La parola chiave closure serve per dichiarare uno speciale tipo di puntatore ad una 

funzione membro. Nel linguaggio C++ standard, il solo modo per ottenere un 
puntatore a una funzione membro consiste nell'utilizzare il nome del membro per 
esteso, come mostrato nell'esempio seguente: 

class base 
{ 

public : 
void func (int x) { } ; 

}; 

typedef void (base::* pBaseMember) (int) ; 
int main (int argc, char* argv[]) 



pBaseMember m = &base: :func; // Get pointer to member 'func' 

// Call 'func' through the pointer to member 
(baseObject.*m) (17) ; 
return 0; 

} 

Tuttavia, non e possibile assegnare un puntatore a un membro di una classe derivata 
a un puntatore a un membro di una classe di base. Questa regola (chiamata 
contravariance) e illustrata nell'esempio seguente: 

class derived: public base 

{ 

public : 
void new_ func (int i) { }; 

}; 

int main (int argc, char* argv[]) 



closure 



base 



baseObject; 



derived 

pBaseMember m = 



derivedObject ; 

Sderived: :new_func; // ILLEGAL 



return 0; 
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L'estensione della parola chiave closure permette di aggirare questa limitazione e 

di fare qualcosa in piu. Utilizzando un closure e possibile ottenere un puntatore a 
funzione membro di un oggetto (cioe una particolare istanza di una classe). L'oggetto 
puo essere qualsiasi oggetto, indipendentemente dalla sua gerarchia di eredita. II 
puntatore this dell'oggetto viene utilizzato automaticamente quando si chiama la 
funzione membro mediante il closure. L'esempio seguente mostra come dichiarare e 
utilizzare un closure. Si presume che le classi base e derivate fornite in precedenza 
siano state definite. 

int main(int argc, char* argv[]) 

{ 

derived derivedObject; 

void (..closure *derivedClosure) (int) ; 

derivedClosure = derivedObject .new_func; // Get a pointer to the 'new_func' member. 

// Note the closure is associated with the 
// particular object, 'derivedObject'. 

derivedClosure (3 ) ; // Call 'new_func' through the closure. 

return 0; 

} 

I closure funzionano inoltre con puntatori a oggetti, come illustrato nell'esempio 
seguente: 

void fund (base *pObj ) 

{ 

//A closure taking an int argument and returning void, 
void ( ...closure *myClosure Mint); 

// Initialize the closure. 
myClosure = pObj->func; 

// Use the closure to call the member function. 
myClosure (1) ; 
return ; 

} 

int main (int argc, char* argv[]) 

{ 

derived derivedObject; 

void (..closure *derivedClosure) (int) ; 

derivedClosure = derivedObject .new_func; // Same as before... 
derivedClosure (3) ; 

// We can use pointers to initialize a closure, too. 

// We can also get a pointer to the 'func' member function 

// in the base class . 

funcl(&derivedObject) ; 

return 0; 

} 

Notare che si sta passando un puntatore a un'istanza della classe derivata e lo si sta 
utilizzando per ottenere un puntatore a una funzione membro nella classe base - una 
cosa che il linguaggio C++ standard non consente di fare. 
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I closure sono una parte fondamentale dell'ambiente RAD di C++ Builder. Essi 
danno la capacita di assegnare un gestore di evento nell'Object Inspector. Ad 
esempio, un oggetto TButton ha un evento di nome OnClick. Nella classe TButton, 
l'evento OnClick e una proprieta che utilizza nella sua dichiarazione l'estensione 

della parola chiave closure. La parola chiave closure permette di assegnare alia 

proprieta una funzione membro di un'altra classe (di solito una funzione membro in 
un oggetto TForm). Quando si colloca un oggetto TButton su una scheda e quindi si 
crea un gestore per l'evento OnClick del pulsante, C++Builder crea una funzione 
membro nel TForm genitore del pulsante e assegna quella funzione membro 
all'evento OnClick di TButton. In questo modo, il gestore di evento viene associato a 
quella particolare istanza di TButton e a nessun altro. 

Per ulteriori informazioni su eventi e closure, vedere il Chapter 48, "Creazione di 
eventi". 

_property 

La parola chiave property dichiara un attributo di una classe. Le proprieta 

appaiono al programmatore esattamente come qualsiasi altro attributo (campo) di 
una classe. Tuttavia, come la sua controparte Object Pascal, la parola chiave 

property di C++Builder aggiunge molte altre funzionalita altre alia semplice 

capacita di esaminare e modificare il valore dell'attributo. Poiche gli attributi della 
proprieta controllano completamente l'accesso alia proprieta, non esistono 
limitazionni sul modo in cui si implementa la proprieta all'interno della stessa classe. 

Sintassi __property type propertyNamelindexlType indexl] [indexNType indexN] = { attributes }; 

in cui 

• type e un tipo di dati intrinseco o dichiarato in precedenza. 

• propertyName e un qualsiasi identificativo valido. 

• indexNType e un tipo di dati intrinseco o dichiarato in precedenza. 

• indexN e il nome di un parametro indice che sara passato alle funzioni read e write 
della proprieta. 

• attributes e una sequenza separata da virgole di read, write, stored, default (o 
nodefault), o index. 

I parametri indexN fra parentesi quadre sono facoltativi. Se presenti, dichiarano una 
proprieta array. I parametri index vengono passati ai metodi read e write della 
proprieta array. 

L'esempio seguente mostra alcune dichiarazioni di proprieta semplici: 

class PropertyExample { 
private: 

int Fx , Fy ; 

float FcellsUOO] [100]; 

protected: 

int readXO { return (Fx) ; } 

void writeX(int newFx) { Fx = newFx; } 

double computeZO { 

// Do some computation and return a floating point value... 
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return (0.0) ; 

} 



float cellValue (int row, int col) { return (Fcells [row] [col] ) ; } 
public: 

..property int X = { read=readx, write=writeX } ; 
..property int Y = { read=Fy } ; 
..property double Z = { read=computeZ }; 

..property float Cells [int row] [int col] = { read=cellValue } ; 

}; 

Questo esempio mostra diverse dichiarazioni di proprieta. La proprieta X ha accesso 
in lettura e scrittura, attraverso le funzioni membro readX e writeX. La proprieta Y 
corrisponde direttamente alia variabile membro Fy ed e a sola lettura. La proprieta Z 
e im valore a sola lettura che viene calcolato; non e memorizzato nella classe come un 
membro dati. Infine, la proprieta Cells dimostra una proprieta array con due indici. 
L'esempio successivo mostra come si acceda a queste proprieta nel codice: 

PropertyExample myPropertyExample; 

myPropertyExample.X = 42; // Evaluates to: myPropertyExample. WriteX(42) ; 

int myVall = myPropertyExample.Y; // Evaluates to: myVall = myPropertyExample. Fy; 
double myVal2 = myPropertyExample . Z ; // Evaluates to: myVal2 = myPropertyExample.ComputeZ ( ) ; 
float cellVal = myPropertyExample [3] [7] ; // Evaluates to: 

// cellVal = myPropertyExample. cellValue (3 , 7) ; 

Le proprieta hanno molte altre varianti e funzionalita non illustrate in questo 
esempio. Gli utenti possono: 

• associare lo stesso metodo di lettura o di scrittura a piu di una proprieta, 
utilizzando l'attributo index 

• specificare valori predefiniti 

• memorizzare le proprieta in un file scheda 

• estendere una proprieta definita in una classe base 

Per maggiori informazioni sulle proprieta, consultare il Capitolo 47, "Creazione di 
proprieta". 

published 

La parola chiave published specifica che le proprieta di quella sezione vengono 

visualizzate nell'Object Inspector, se la classe si trova nella tavolozza Component. 
Solo le classi derivate da TObject possono avere sezioni published. 

Le regole di visibility per i membri pubblicati sono identiche a quelle dei membri 
pubblici. L'unica differenza tra membri pubblicati e pubblici e che le informazioni di 
tipo runtime in stile (RTTI) di Object Pascal vengono generate per i membri dati e per 

le proprieta dichiarate in una sezione published. RTTI consente ad 

un'applicazione di sottoporre a query in modo dinamico i membri dati, le funzioni 
membro e le proprieta di un tipo di classe altrimenti sconosciuto. 

In una sezione published non sono consentiti ne costruttori ne distruttori. Le 

proprieta, i membri dati Pascal intrinseci o derivati della VCL o della CLX, le 
funzioni membro e i closure sono ammessi solo in una sezione published. I campi 
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definiti in una sezione published devono essere di un tipo classe. Le proprieta 

definite in una sezione published non possono essere proprieta array. II tipo di 

una proprieta definito in una sezione published deve essere un tipo ordinale, un 

tipo real, un tipo stringa, un tipo small set, un tipo classe, o un tipo puntatore a 
metodo. 

Estensione della parola chiave _declspec 



Alcuni argomenti per l'estensione della parola chiave declspec forniscono il 

supporto del linguaggio per la VCL e la CLX. Questi argomenti sono elencati di 
seguito. Le macro per gli argomenti declspec e le loro combinazioni vengono definite 
in sysmac.h. Nella maggior parte dei casi non occorre specificarli. Quando e 
necessario aggiungerli, si devono usare le macro. 

_declspec(delphiclass) 

L'argomento delphiclass viene usato per le dichiarazioni di classi derivate da 
TObject. Queste classi vengono create con le seguenti compatibilita: 

• RTTI compatibile con la VCL 

• comportamento del costruttore/distruttore compatibile con la VCL 

• gestione delle eccezioni compatibile con la VCL 

Una classe compatibile con la VCL o la CLX ha le seguenti restrizioni: 

• non e consentita alcuna classe base virtuale. 

• non e consentita alcuna eredita multipla salvo nel caso descritto in "Eredita e 
interfacce" on page 13-2. 

• deve essere allocata dinamicamente usando l'operatore globale new. 

• deve avere un distruttore. 

• i costruttori di copia e gli operatori di assegnazione non vengono generati dal 
compilatore per le classi derivate dalla VCL e dalla CLX. 

Una dichiarazione di classe che viene tradotta da Object Pascal richiede questo 
modificatore se il compilatore ha bisogno di sapere se la classe e derivata da TObject. 

_declspec(delphireturn) 

In C++Builder, l'argomento delphireturn e usato solo internamente dalla VCL e 
dalla CLX. Viene usato per le dichiarazioni delle classi che sono state create in 
C++Builder per supportare i tipi di dati incorporati di Object Pascal e i costrutti del 
linguaggio, dato che essi non hanno un tipo C++ native Questi includono Currency, 
AnsiString, Variant, TDateTime e Set. L'argomento delphireturn contrassegna le classi 
C++ per la gestione della compatibilita VCL e CLX in chiamate a funzioni come 
parametri e nella restituzione di valori. Questo modificatore e necessario quando si 
passa una struttura per valore ad una funzione tra Object Pascal e C++. 
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declspec(delphirtti) 

L'argomento delphirtti fa si che il compilatore includa in una classe le informazioni 
di tipo in esecuzione quando tale classe viene compilata. Quando si utilizza questo 
modificatore, il compilatore genera informazioni di tipo in esecuzione per tutti i 
campi, metodi e proprieta che sono stati dichiarati in una sezione published. Nel caso 
delle interfacce, il compilatore genera le informazioni di tipo in esecuzione per tutti i 
metodi dell'interfaccia. Se una classe viene compilata con le informazioni di tipo in 
esecuzione, anche tutti i suoi discendenti includono le informazioni di tipo in 
esecuzione. Poiche la classe TPersistent viene compilato includendo le informazioni 
di tipo in esecuzione, cio significa che non c'e alcuna necessita di utilizzare questo 
modificatore con le classe che vengono create e il cui antenato e TPersistent. Questo 
modificatore viene utilizzato principalmente per le interfacce in applicazioni che 
implementano o utilizzano Web Services. 

_declspec(dynamic) 

L'argomento dynamic viene usato per le dichiarazioni delle funzioni dinamiche. 
Queste funzioni sono simili alle funzioni virtuali, tranne per il fatto vengono 
memorizzate nelle vtables per gli oggetti che le definiscono, non nelle vtables dei 
discendenti. Se si chiama una funzione dinamica che non e definita nell'oggetto, la 
ricerca viene effettuata nelle vtables dei suoi antenati finche la funzione non viene 
trovata. Le funzioni dinamiche sono valide solo per le classi derivate da TObject. 

_declspec(hidesbase) 

L'argomento hidesbase preserva la semantica di programma di Object Pascal 
quando si esportano le funzioni virtuali di Object Pascal e si ridefiniscono per 
C++Builder. In Object Pascal le funzioni virtuali delle classi base possono apparire 
nella classe derivata come funzioni con lo stesso nome, destinate ad essere funzioni 
completamente nuove senza alcuna relazione esplicita con quelle precedenti. 

I compilatori usano la macro HIDESBASE, definita in sysmac.h, per specificare che 
questi tipi di dichiarazione delle funzioni sono completamente diversi. Per esempio, 
se una classe base Tl dichiara una funzione virtuale,/wnc, senza acquisire alcun 
argomento, e la sua classe derivata T2 ha dichiarato una funzione con lo stesso nome 
e signature, DCC32 -jphn produrra un file HPP con il seguente prototipo: 

virtual void Tl :: func (void) ; 
HIDESBASE void T2 : : func ( void) ; 

Senza la dichiarazione HIDESBASE, la semantica di programma di C++ indica che la 
funzione virtuale Tl::func() deve essere ridefinita dalla T2::func(). 

_declspec(package) 

L'argomento package indica che il codice che def inisce la classe puo essere compilato 
in un package. Questo modificatore viene generato automaticamente dal compilatore 
quando vengono creati i package nell'IDE. Per maggiori informazioni sui package, 
consultare il Capitolo 15, "Uso di package e di componenti". 
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_declspec(pascalimplementation) 

L'argomento pascalimplementation indica che il codice che definisce la classe e stato 
implementato in Object Pascal. Questo modificatore appare in un file header di 
portability Object Pascal con estensione .hpp. 

_declspec(uuid) 

L'argomento uuid associa una classe con un identificativo globalmente univoco 
(GUID). Questi puo essere utilizzato con qualsiasi classe, ma, di solito, viene 
utilizzato con classi che rappresentano interfacce di Object Pascal (o interfacce COM). 
E possibile ottenere il GUID di una classe che e stata dichiarata utilizzando questo 
modificatore chiamando la direttiva uuidof . 
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Capitolo 




Sviluppo di applicazioni 
multipiattaforma 

E possibile utilizzare C++Builder per sviluppare applicazioni a 32 bit 
multipiattaforma eseguibili sia nel sistema operativo Windows sia nel sistema 
operativo Linux. Le applicazioni multipiattaforma utilizzano componenti CLX e non 
eseguono alcuna chiamata specifica alle API del sistema operativo. Per sviluppare 
un'applicazione multipiattaforma e possibile sia creare una nuova applicazione CLX 
sia modificare un'applicazione Windows esistente. Quindi la si deve compilare e 
distribuire sulla piattaforma su cui la si dovra eseguire. Per l'ambiente Windows, 
utilizzare C++Builder. Per l'ambiente Linux, una soluzione C++ di Borland non e 
ancora disponibile, ma ci si puo preparare per tempo sviluppando da ora le proprie 
applicazioni con C++Builder. 

Questo capitolo descrive come modificare le applicazioni scritte in C++Builder in 
modo da poterle compilare in ambiente Linux e come scrivere del codice 
indipendente dalla piataforma e portabile fra i due ambienti. Questo capitolo include 
inoltre informazioni sulle differenze fra lo sviluppo di applicazioni nei due ambienti 
Windows e Linux. 

Creazione di applicazioni multipiattaforma 



E possibile creare applicazioni multipiattaforma nello stesso modo in cui si creano le 
normali applicazioni in C++Builder. Se si vuole che l'applicazione sia perfettamente 
multipiattaforma e necessario utilizzare componenti visuali e non della CLX e non si 
dovrebbero utilizzare chiamate API specifiche del sistema operativo. (Per 
informazioni sulla scrittura di applicazioni multipiattaforma consultare "Scrittura di 
codice portabile" a pagina 14-17.) 

Per creare un'applicazione multipiattaforma: 

1 Nell'IDE, scegliere il comando File I New I CLX application. 
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di applicazioni Windows in Linux 



La Component palette visualizzera i componenti e le pagine che si possono 
utilizzare nelle applicazioni CLX. 

2 Sviluppare l'applicazione all'interno dell'IDE. 

3 Compilare e collaudare l'applicazione. Esaminare gli eventuali messaggi di errore 
per vedere dove e necessario apportare ulteriori modifiche. 

Non appena sara diponibile una soluzione C++Builder per Linux, sara possibile 
compilare ed eseguire il collaudo in ambiente Linux. 

Quando si eseguira il porting dell'applicazione su Linux, sara necessario impostare 
di nuovo le opzioni del progetto. Questo perche il file .dof che contiene le opzioni di 
progetto viene ricreato in Linux con una diversa estensione (con il set di opzioni 
predefinite). 

I file scheda nella applicazioni multipiattaforma hanno l'estensione . xfm invece 
di.dfm. Questo per distingue le schede per multipiattaforma che utilizzano 
componenti CLX dalle schede che utilizzano componenti della VCL. Una scheda.xfm 
funziona su entrambe le piattaforme Windows e Linux mentre una scheda .dfm 
funziona solo in ambiente Windows. 

Per informazioni sulla scrittura di applicazioni database o Internet indipendenti dalla 
piattaforma, consultare "Applicazioni database multipiattaforma" a pagina 14-21 
and "Applicazioni Internet multipiattaforma" a pagina 14-30. 



Porting di applicazioni Windows in Linux 



Se si hanno applicazioni C++Builder scritte per l'ambiente Windows, e possibile 
convertirle per l'ambiente Linus. La facilita dell'operazione dipende dalla natura e 
dalla complessita dell'applicazione e da quante dipendenze esplicite a Windows essa 
include. 

Le sezioni seguenti descrivono le principali differenze fra gli ambienti Windows e 
Linux e forniscono una serie di regole generali per iniziare immediatamente ad 
effettuare il porting di un'applicazione. 

Tecniche di porting 



Di seguito sono elencate le varie strade che e possibile intraprendere per trasportare 
un'applicazione da una piattaforma a una altra: 

Tabella 14.1 Tecniche di porting 

Tecnica Descrizione 

Porting specifico per Ha come obiettivo un sistema operativo e le API sottostanti 
una piattaforma 

Porting per piu Ha come obiettivo un'API per piu piattaforme 
piattaforme 

Emulazione Windows Lascia inalterato il codice ed esegue il porting delle API utilizzate 
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Porting specifico per una piattaforma 

I porting specifici per una certa piattaforma tendono a essere laboriosi, costosi e 
producono solo un singolo risultato mirato. Tali conversioni creano basi di codice 
differenti, il che rende il codice particolarmente difficile da gestire. Tuttavia, ogni 
porting e progettato per uno specifico sistema operativo e puo sfruttare le 
funzionalita specifiche della piattaforma. Pertanto, l'applicazione di solito viene 
eseguita piu rapidamente. 

Porting per piu piattaforme 

II porting per piu piattaforme tende a far risparmiare tempo in quanto l'applicazione 
risultante ha come obiettivo piu piattaforme. Nella realta, la quantita di lavoro 
necessario per lo sviluppo di applicazioni multipiattaforma dipende fortemente dal 
codice esistente. Se il codice e stato sviluppato senza rispetto per l'indipendenza 
dalla piattaforma, ci si potrebbe imbattere in situazioni in cui la "logica" 
indipendente dalla piattaforma e l'"implementazione" dipendente dalla piattaforma 
risultano mischiate. 

L'approccio multipiattaforma e l'approccio preferibile perche la logica di gestione 
viene espressa in termini indipendenti dalla piattaforma. Alcuni servizi vengono resi 
astratti e nascosti dietro un'interfaccia interna che ha lo stesso aspetto lo stesso su 
tutte le piattaforme, ma ha un'implementazione specifica per ognuna di esse. La 
libreria runtime di C++Builder ne e un tipico esempio. L'interfaccia e molto simile su 
entrambe le piattaforme, anche se limplementazione puo essere notevolmente 
differente. Si dovrebbe separare le sezioni indipendenti dalla piattaforma, quindi 
implementare su di esse i servizi specifici. Alia fine, questo approccio risulta essere la 
soluzione meno dispendiosa, grazie ai costi di manutenzione ridotti derivanti dalla 
condivisione della maggior parte dei sorgenti di base e dal miglioramento 
dell'architettura dell'applicazione. 

Porting in emulazione Windows 

L'emulazione di Windows e il metodo piu complesso e puo risultare molto 
dispendioso, anche se l'applicazione Linux risultante sara molto simile a 
un'applicazione Windows esistente. Questo approccio implica l'implementazione in 
Linux di funzionalita tipiche di Windows. Da un punto di vista architetturale, questa 
soluzione e molto difficile da gestire. 

Nel caso si vogliano emulare le API di Windows, e possibile includere due sezioni 
distinte utilizzando le direttive #ifdef in modo da indicare le sezioni di codice 
dedicate specificatamente all'ambiente Windows o a quello Linux. 

Porting dell'applicazione 



Se si effettua il porting di un'applicazione che si vuole eseguire su entrambe le 
piattaforme Windows e Linux, sara necessario modificare il codice oppure utilizzare 
direttive #ifdef per indicare le sezioni di codice dedicate specificatamente 
all'ambiente Windows o a quello Linux. 
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Per eseguire il porting di un'applicazione VCL in CLX, fare quanta segue: 

1 Aprire in C++Builder il progetto che contiene l'applicazione che si desidera 
modificare. 

2 Copiare i file .dfm in file .xfm aventi lo stesso nome (ad esempio, rinominare 
unitl.dfm in unitl.xfm). Rinominare (o includere in direttive #ifdef) il riferimento 
al file .dfm nel file header da ♦pragma resource 11 *.dfm" to ♦pragma resource "*. xfm". (II file 
.xfm funzionera sia in applicazioni C++Builder sia in Linux.) 

3 Modificare (o includere in direttive #if def) tutti i file header nel file sorgente in 
modo che facciano riferimento alle corrette unit nella CLX. (Per informazioni, 
consultare "Confronto fra le unit CLX e VCL" a pagina 14-9.) 

Ad esempio, modificare le seguenti istruzione #include nel file header di 
un'applicazione Windows: 

♦include <vcl.h> 
♦include <Controls .hpp> 
♦include <StdCtrls .hpp> 
♦include <Forms.hpp> 

to the following for a CLX application: 

♦include <clx.h> 
♦include <QControls .hpp> 
♦include <QStdCtrls .hpp> 
♦include <QForms.hpp> 

4 Salvare il progetto e riaprirlo. Ora la Component palette visualizzera i componenti 
che si possono utilizzare nelle applicazioni CLX. 

Nelle applicazioni CLX possono essere utilizzati solo alcuni componenti non 
visuali di Windows che pero contengono funzionalita che possono essere 
utilizzate solo in applicazioni CLX di Windows. Se si prevede di compilare 
l'applicazione anche su Linux, non utilizzare componenti della VCL non visuali 
oppure utilizzare istruzioni condizionali #if def per contrassegnare queste sezioni 
di codice come utilizzabili solo per Windows. Non e possibile utilizzare nella 
stessa applicazione la parte visuale della VCL con VisualCLX. 

5 Riscrivere tutto il codice che richiede dipendenze Windows, rendendolo il piu 
possibile indipendente dalla piattaforma. A questo scopo utilizzare le routine e le 
costanti della libreria di runtime. (Per informazioni consultare "Scrittura di codice 
portabile" a pagina 14-17.) 

6 Trovare le funzionalita equivalenti per quelle funzioni che sono diverse in Linux. 
Utilizzare #ifdef (con moderazione) per delimitare le informazioni specifiche per 
Windows. (Per informazioni consultare "Utilizzo delle direttive condizionali" a 
pagina 14-18.) 

Ad esempio, nel file sorgente e possibile delimitare con direttive #ifdef il codice 
specifico per la piattaforma: 

♦ifdef WINDOWS //If using the C++Builder compiler, use __WIN32__ 
IniFile->LoadfromFile ( "c: \ \x.txt" ) ; 
♦endif 
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ttifdef __linux__ 

IniFile->LoadfromFile ( "/home/name/x. txt" ) ; 
#endif 

7 Cercare in tutti i file di progetto i riferimenti ai nomi di percorso. 

• Nei percorsi di Linux si utilizza come delimitatore una barra diritta / (ad 
esempio, /usr/lib) e i file possono essere situati in varie directory nel sistema 
Linux. Utilizzare la costante PathDelim (in SysUtils) per specificare il 
delimitatore di percorso appropriate per il sistema. Determinare l'ubicazione 
corretta per tutti i file in Linux. 

• Modificare i riferimenti alle lettere di unita (ad esempio, C: \) e il codice che 
ricava le lettere associate alle unita ricercando il carattere due punti alia 
posizione 2 nella stringa. Utilizzare la costante DriveDelim (in SysUtils) per 
specificare l'ubicazione in modo appropriato per il sistema. 

• Nei segmenti di codice in cui si specificano percorsi multipli, modificare il 
separatore di percorso da punto e virgola (;) a due punti (:). Utilizzare la 
costante PathSep (in SysUtils) per specificare il separatore di percorso 
appropriato per il sistema. 

• Poiche in Linux i nomi dei file sono sensibili all'uso delle maiuscole e 
minuscole, assicurarsi che l'applicazione non modifichi i caratteri maiuscoli/ 
minuscoli dei nomi dei file o non faccia affidamento su di essi. 

8 Compilare, collaudare ed eseguire il debug dell'applicazione. 

CLX e VCL 

CLX utilizza la Component Library per Cross Platform (CLX) di Borland invece della 
Visual Component Library (VCL). All'interno della VCL, molti controlli consentono 
di accedere facilmente ai controlli Windows eseguendo chiamate nelle librerie API di 
Windows. Analogamente, la CLX consente l'accesso ai Qt widget (il nome deriva 
dalle parole window e gadget) nelle librerie condivise Qt. C++Builder include sia la 
CLXsialaVCL. 

La CLX e molto simile alia VCL. La maggior parte dei componenti e delle proprieta 
hanno gli stessi nomi. Inoltre, la CLX, come anche la VCL, e disponibile in ambiente 
Windows (a seconda dell'edizione di C++Builder che si possiede). 

I componenti CLX possono essere raggruppati come segue: 

Tabella 14.2 Sezioni della CLX 
Sezione Descrizione 

VisualCLX Componenti GUI e grafici nativi multipiattaforma. 

DataCLX Componenti client per l'accesso ai dati. I componenti in questa sezione 

sono un sottoinsieme dei componenti locali, client/ server e n-tier basati 
sui dataset client. II codice e lo stesso in Linux e in Windows. 
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Tabella 14.2 Sezioni dellaCLX 


Sezione 


Descrizione 


NetCLX 


Componenti Internet tra cui Apache DSO e CGI WebBroker. Questi sono 
identici in Linux e in Windows. 


BaseCLX 


Libreria di runtime aggiornata e comprensiva di unit Classes. 11 codice e 
lo stesso in Linux e in Windows. 



I widget in VisualCLX sostituiscono i controlli Windows. Ad esempio, 
TWidgetControl nella CLX sostituisce TWidgetControl nella VCL. Altri componenti 
della VCL (come TScrollingWincontrol) hanno nomi corrispondenti nella CLX (come 
TScrollingWidget). Tuttavia, non e necessario modificare ad esempio tutte le 
ricorrenze di TWinControl in TWidgetControl. Dichiarazioni di tipo, come ad esempio: 

TWinControl = TWidgetControl; 

appaiono nel file unit QControls per semplificare la condivisione del codice sorgente. 
TWidgetControl e tutti i suoi discendenti hanno una proprieta Handle che referenzia 
l'oggetto Qt e una proprieta Hooks che referenzia l'oggetto hook object che gestisce il 
meccanismo degli eventi. 

Nella CLX i nomi delle unit e l'ubicazione di alcune classi sono differenti. Sara 
necessario modificare il file header incluso nel file sorgente per eliminare i riferimenti 
alle unit che non esistono nella CLX e modificare i nomi in quelli delle unit della 
CLX. 

Differenze nella CLX 



Benche quasi tutta la CLX sia implementata in modo da essere compatibile con la 
VCL, alcune funzioni sono implementate diversamente. Questa sezione fornisce una 
panoramica su alcune differenze esistenti fra le implementazioni della CLX e della 
VCL che occorre tener presente durante la scrittura di applicazioni multipiattaforma. 

Aspetto 

L'ambiente visuale in Linux e abbastanza differente rispetto a Windows. L'aspetto 
delle finestre di dialogo puo essere diverso a seconda del Windows manager 
utilizzato, come ad esempio KDE o Gnome 

Stili 

Oltre alle proprieta OwnerDraw e possibile utilizzare " stili" a livello di applicazione. 
E possibile utilizzare la proprieta TApplication::Style per specificare l'aspetto degli 
elementi grafici di un'applicazione. Utilizzando gli stili, un widget o un'applicazione 
puo assumere un aspetto completamente differente. In Linux e sempre possibile 
utilizzare uno stile owner draw ma si consiglia l'utilizzo degli stili. 

Variant 

Tutto il codice relativo a variant e safe array che era inserito nella unit System e 
incluso in due nuove unit: 
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• Variants 

• VarUtils 

II codice dipendente dal sistema operativo e ora isolato nella unit VarUtils, che 
contiene anche versioni generiche di tutto do che le e necessario. Se si sta 
convertendo un'applicazione VCL che includeva chiamate Windows in 
un'applicazione CLX, e necessario sostituire queste chiamate con chiamate nella unit 
VarUtils. 

Se si desidera utilizzare dei variant, e necessario includere la unit Variants al file 
header del file sorgente. 

VarlsEmpty esegue un semplice controllo su varEmpty per vedere se un variant e 
vuoto mentre su Linux e possibile utilizzare la funzione VarlsClear per verificare se il 
valore del variant e indefinito. 

File di registro 

Linux non utilizza un file di registro per memorizzare le informazioni di 
configurazione. Invece, al posto del file di registro, si utilizzano file di configurazione 
di testo e variabili di ambiente. I file di configurazione di sistema su Linux sono 
situati spesso in /etc, ad esempio, in /etc/host. Altri profili utente sono situati in file 
nascosti (preceduti da un punto), come .bashrc, che contiene impostazioni della shell 
bash, oppure .XDefaults, utilizzato per memorizzare le impostazioni predefinite dei 
programmi X. 

II codice dipendente dal file di registro puo essere modificato in modo da utilizzare al 
suo posto un file di testo di configurazione locale. Le impostazioni modificabili 
dall'utente possono essere salvate nella directory personale in modo che l'utente 
abbia i diritti di scrittura. Le opzioni di configurazione che e necessario impostare 
dalla radice dovrebbero andare in / etc.Un modo per gestire una precedente 
dipendenza dal file di registro e quello di scrivere una unit che includa tutte le 
funzioni relative al file di registro, dirigendo pero tutto l'output su un file di 
configurazione locale. 

Se si vogliono collocare delle informazioni in una posizione globale in ambiente 
Linux, e possibile registrare un file di configurazione globale nella directoryy / etc o 
nella directory home dell'tente come file nascosto. In questo modo tutte le 
applicazioni potranno accedere alio stesso file di configurazione. Tuttavia, e 
necessario accertarsi che le autorizzazioni sui file e i diritti di accesso siano 
configurati correttamente. 

Anche nelle applicazioni multipiattaforma e possibile utilizzare i file .ini. Tuttavia, 
nella CLX, e necessario utilizzare TMemlniFile invece di TReglniFile. 

Altre differenze 

L'implementazione di CLX presenta anche altre differenze rispetto alia VCL che 
influiscono sulla modalita di funzionamento dei componenti. Questa sezione 
descrive alcune di queste differenze. 

• E possibile selezionare un componente CLX dalla Component palette e fare 
indifferentemente clic col pulsante destro o sinistro per aggiungerlo a una scheda. 
Nel caso di componenti VCL, e possibile solo fare clic col pulsante sinistro. 
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• II controllo TButton della CLX ha una proprieta ToggleButton che l'equivalente 
controllo della VCL non possiede. 

• In CLX, TColorDialog non ha una proprieta TColorDialog: :Options da impostare. 
Quindi, e impossibile personalizzare l'aspetto e le funzionalita della finestra di 
dialogo dei colori. Inoltre, a seconda del window manager utilizzato in Linux, 
TColorDialog non sempre e modale o con dimensioni fisse. In ambiente Windows, 
TColorDialog e sempre modale e non dimensionabile. 

• In fase di esecuzione, le caselle combinate della CLX funzionano in modo diverso 
rispetto a quelle della VCL. Nella CLX (ma non nella VCL), e possibile aggiungere 
un elemento a un elenco a discesa immettendo del testo nel campo di editing di 
una casella combinata e premendo il tasto Invio. E possibile disattivare questa 
funzione impostando InsertMode a ciNone. E anche possibile aggiungere elementi 
vuoti (nessuna stringa) alia lista della casella combinata. Inoltre, se si tiene 
premuto il tasto freccia giu, non ci si ferma sull'ultimo elemento dell'elenco della 
casella combinata. Si torna nuovamente all'inizio. 

• TCustomEdit non implementa Undo, Clearllndo o Canllndo. Pertanto non esiste 
alcun modo per annullare da programma le modifiche. In fase di esecuzione, gli 
utenti dell'applicazione potranno comunque annullare le modifiche apportate a 
una casella di testo (TEdit) facendo clic destro sulla casella di modifica e scegliendo 
il comando Undo. 

• I valori dei tasti usati negli eventi possono essere differenti fra la VCL e la CLX. Ad 
esempio, il tasto Invio ha un valore pari a 13 nella VCL e un valore pari a 4100 
nella CLX. Se nelle applicazioni CLX il valore dei tasti e stato inserito nel codice, 
sara necessario modificare tali valori quando si eseguira il porting da Windows a 
Linux o viceversa. 

Esistono anche altre differenze. Per i dettagli su tutti gli oggetti della CLX, fare 
riferimento alia documentazione in linea relativa alia CLX, oppure, nelle versioni di 
C++Builder che includono il codice sorgente, e possibile consultare direttamente il 
codice che e situato nella directory {directory di installazione}\C++Builder6\ 
SourceXCLX. 

Cosa manca nella CLX 



Se si utilizza la CLX invece della VCL, si potra notare che molti oggetti sono identici. 
Tuttavia, gli oggetti potrebbero non avere tutte le funzionalita (come proprieta, 
metodi o eventi). Nella CLX mancano le seguenti funzionalita generali: 

• Proprieta bidirezionali (BidiMode) per input/output di testo da destra a sinistra. 

• Proprieta bevel generiche sui controlli comuni (si noti che alcuni oggetti hanno 
ancora proprieta bevel). 

• Proprieta e metodi per l'aggancio. 

• Funzionalita per la compatibilita con versioni precedenti come i componenti sulle 
pagina Win3.1 e Ctl3D. 

• DragCursor e DragKind (anche se le funzioni drag-and-drop sono incluse). 
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Funzioni di cui non e possibile fare il porting 



Alcune caratteristiche specifiche di Windows supportate in C++Builder non possono 
essere portate direttamente in ambienti Linux. Ad esempio, funzionalita quali COM, 
ActiveX, OLE, BDE e ADO sono dipendenti dalla tecnologia Windows e non sono 
disponibili per Linux. La tabella seguente elenca le funzionalita che differiscono sulle 
due piattaforme e, nel caso sia disponibile, elenca l'equivalente funzionalita Linux o 
della CLX. 



Tabella 14.3 Funzionalita modificate o differenti 

Funzionalita Linux/CLX 

Normali componenti database 



Funzionalita Windows/VCL 

Componenti ADO 
Automation Server 
BDE 

Componenti COM (inclusi ActiveX) 

DataSnap 

FastNet 

Componenti precedenti (come gli 
elementi sulla pagina Win 3.1 della 
Component palette) 

Messaging Application Programming 
Interface (MAPI) include una libreria 
standard di funzioni Windows per 
l'invio di messaggi. 

Quick Reports 

Web Services (SOAP) 

WebSnap 

Chiamate alle API di Windows 

Invio messaggi Windows 
Winsock 



Non disponibili 

dbExpress e normali componenti database 
Non disponibili 
Non disponibili 
Non disponibili 
Non disponibili 



SMTP e POP3 permettono di inviare, ricevere e salvare 
messaggi di posta elettronica 



Non disponibili 
Non disponibili 
Non disponibili 

Metodi CLX, chiamate QT, chiamate alia libc o chiamate 
ad altre librerie di sistema 

Eventi Qt 

BSD sockets 



L'equivalente Linux delle DLL di Windows sono le librerie di oggetti condivisi (file 
.so), che contengono codice indipendente dalla posizione (PIC). Quindi, i riferimenti 
di memoria globali e le chiamate a funzioni esterne sono tutti relativi al registro EBX, 
che deve essere salvaguardato durante le chiamate. 

E necessario preoccuparsi dei riferimenti di memoria globali e delle chiamate a 
funzioni esterne solo nel caso si utilizzi l'assembler - C++Builder e in grado di 
generare il codice corretto. (Per informazioni, vedere "Inclusione di codice assembler 
in linea" a pagina 14-20.) 

Confronto fra le unit CLX e VCL 



Tutti gli oggetti nella VCL o nelle CLX sono definiti in file header. Ad esempio, e 
possibile trovare l'implementazione di TObject nella unit System e la unit Classes 
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definisce la classe di base TComponent. Quando si rilascia un oggetto su una scheda o 
si utilizza un oggetto all'interno dell'applicazione, il nome della unit viene aggiunto 
al file header incluso nel file sorgente, che dice al compilatore quali sono le unit di cui 
eseguire il link nel progetto. 

Questa sezione presenta tre tabelle che elencano le unit equivalenti fra VCL e CLX 
units, le unit specifiche per la CLX e le unit specifiche per la VCL. 

La seguente tabella elenca la unit nella VCL e quella equivalente nella CLX. Non sono 
riportate le unit identiche nella VCL e nella CLX, oppure le unit fornite da produttori 
terzi. 

Tabella 14.4 Unit nella VCL ed equivalenti nella CLX 
Unit della VCL Unit della i 



ActnList QActnList 

Buttons QButtons 

CheckLst QCheckLst 

Clipbrd QClipbrd 

ComCtrls QComCtrls 

Consts Consts, QConsts, and RTLConsts 

Controls QControls 

DBActns QDBActns 

DBCtrls QDBCtrls 

DBGrids QDBGrids 

Dialogs QDialogs 

ExtCtrls QExtCtrls 

Forms QForms 

Graphics QGraphics 

Grids QGrids 

ImgList QlmgList 

Mask QMask 

Menus QMenus 

Printers QPrinters 

Search QSearch 

StdActns QStdActns 

StdCtrls QStdCtrls 

Types Types and QTypes 

VclEditors ClxEditors 



Le seguenti unit sono nella CLX ma non nella VCL: 

Tabella 14.5 Unit solo nella CLX 
Unit Descrizione 

DirSel Selezione di directory 
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Tabella 14.5 Unit solo nella CLX 
Unit Descrizione 

QStyle Aspetto della GUI 

Qt Interfaccia per la 

libreria Qt 



Le seguenti unit VCL per Windows non sono incluse nella CLX principalmente 
perche sono relative a funzionalita specifiche di Windows, come ADO, COM e BDE, 
che non sono disponibili in Linux. 



Tabella 14.6 Unit solo 
Unit 

ADOConst 

ADODB 

AppEvnts 

AxCtrls 

BdeConst 

Calendar 

Chart 

CmAdmCtl 

ColorGrd 

ComStrs 

ConvUtils 

CorbaCon 

CorbaStd 

CorbaVCL 

CtlPanel 

CustomizeDlg 

DataBkr 

DBCGrids 

DBExcept 

DBInpReq 

DBLookup 

DbOleCtl 

DBPWDlg 

DBTables 

DdeMan 

DRTable 

ExtActns 

ExtDlgs 

FileCtrl 



nella VCL 

Motivo dell'esclusione 

Nessuna funzionalita ADO 

Nessuna funzionalita ADO 

Nessun oggetto TApplicationEvent 

Nessuna funzionalita COM 

Nessuna funzionalita BDE 

Non supportata 

Non supportata 

Nessuna funzionalita COM 

Non supportata 

Nessuna funzionalita COM 

Non disponibili 

Nessuna funzionalita Corba 

Nessuna funzionalita Corba 

Nessuna funzionalita Corba 

Nessun supporto per Windows 
Control Panel 

Non supportata 

Non supportata 

Nessuna funzionalita BDE 

Nessuna funzionalita BDE 

Nessuna funzionalita BDE 

Obsoleta 

Nessuna funzionalita COM 

Nessuna funzionalita BDE 

Nessuna funzionalita BDE 

Nessuna funzionalita DDE 

Nessuna funzionalita BDE 

Non supportata al momento 

Nessuna funzionalita per finestre di 
dialogo con picture 

Obsoleta 
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Tabella 14.6 Unit solo 
Unit 

ListActns 

MConnect 

Messages 

MidasCon 

MPlayer 

Mtsobj 

MtsRdm 

Mtx 

mxConsts 

ObjBrkr 

OleConstMay 

OleCtnrs 

OleCtrls 

OLEDB 

OleServer 

Outline 

Registry 

ScktCnst 

ScktComp 

SConnect 

SHDocVw_ocx 

StdConvs 

SvcMgr 

TabNotbk 

Tabs 

ToolWin 

ValEdit 

VarCmplx 

VarConv 

VCLCom 

WebConst 

Windows 



nella VCL 

Motivo dell'esclusione 

Non supportata 

Nessuna funzionalita COM 

Nessuna gestione messaggi di 
Windows 

Obsoleta 

Non esiste media player di Windows 
Nessuna funzionalita COM 
Nessuna funzionalita COM 
Nessuna funzionalita COM 
Nessuna funzionalita COM 
Non supportata 
Nessuna funzionalita COM 
Nessuna funzionalita COM 
Nessuna funzionalita COM 
Nessuna funzionalita ADO 
Nessuna funzionalita COM 
Obsoleta 

Nessuna funzionalita per il registry di 
Windows 

Sostituito da Sockets 

Sostituito da Sockets 

Protocolli di connessione non 
supportati 

Nessuna funzionalita ActiveX 
Non supportata 

Nessuna funzionalita per i servizi NT 
di Windows 

Obsoleta 

Obsoleta 

Nessuna funzionalita di aggancio 

Non supportata al momento 

Non supportata al momento 

Non supportata al momento 

Nessuna funzionalita COM 

Nessuna costante Windows 

Nessuna chiamata alle API di 
Windows 
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Differenze nei costruttori di oggetti CLX 



Quando si crea un oggetto CLX, o implicitamente, collocando quell'oggetto sulla 
scheda, o esplicitamente nel codice, utilizzando il costruttore dell'oggetto, viene 
creata anche un'istanza del widget associato sottostante. L' oggetto CLX possiede 
questa istanza del widget. Quando l'oggetto della CLX viene cancellato viene 
cancellato anche il widget sottostante. Questo e lo stesso tipo di funzionalita che e 
possibile trovare nella VCL nelle applicazioni Windows. 

Quando nel codice si crea esplicitamente un oggetto CLX mediante una chiamata alia 
libreria delle interfacce di QT come QWidget_Create(), si sta creando un'istanza di un 
widget QT che non e posseduto da un oggetto CLX. In questo modo si passa 
all'oggetto CLX l'istanza di un widget Qt esistente da utilizzare durante la sua 
costruzione. Questo oggetto CLX non possiede il widget Qt che gli viene passato. 
Quindi, dopo avere creato l'oggetto in questo modo, viene distrutto solo l'oggetto 
CLX e non l'istanza del widget Qt sottostante. Questo comportamento e diverso 
rispetto a quello della VCL. 

Alcuni oggetti grafici della CLX, come TBrush e TPen, permettono di assumere la 
proprieta del widget sottostante utilizzando il metodo OwnHandle. Dopo avere 
chiamato OwnHandle, se si cancella l'oggetto CLX, viene distrutto anche il widget 
sottostante. 

Alcune assegnazioni di proprieta nella CLX sono state spostate dal costruttore a 
InitWidget. Cio consente di ritardare la costruzione dell'oggetto Qt finche non sara 
veramente necessario. Ad esempio, si supponga di avere una proprieta di nome 
Color. In SetColor, e possibile interrogare HandleAllocated per controllare se si dispone 
di un handle Qt. Se lo handle e allocato, e possibile effettuare la chiamata corretta a 
Qt per impostare il colore. Nel caso non lo sia, e possibile memorizzare il valore in 
una variabile di campo privata e impostare la proprieta in InitWidget. 

Per maggiori informazioni sulla costruzione di oggetti, vedere "Costruzione di 
oggetti per le classi VCLXCLX di C++Builder" a pagina 13-8. 

Gestione degli eventi di sistema e di widget 



Gli eventi di sistema e di widget, che sono la preoccupazione principale quando si 
scrivono componenti, sono gestiti in modo diffferente dalla VCL e dalla CLX. La 
differenza piu importante e che i controlli CLX non rispondono direttamente ai 
messaggi di Windows, anche quando sono in esecuzione in ambiente Windows 
(vedere il Capitolo 51, "Gestione dei messaggi e delle notifiche di sistema"). Invece, 
essi rispondono alle notifiche provenienti dallo strato del widget sottostante. Poiche 
le notifiche utilizzano un sistema diverso, l'ordine e la sincronizzazione degli eventi 
possono essere diversi talvolta tra oggetti CLX e VCL corrispondenti. Tale differenza 
e riscontrabile anche quando l'applicazione CLX viene eseguita in ambiente 
Windows piuttosto che in Linux. Se si esegue il porting di un'applicazione VCL a 
CLX, per gestire queste differenze potrebbe essere necessario modificare il modo in 
cui i gestori di evento reagiscono agli eeventi. 
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Per informazioni sulla scrittura di componenti che rispondono a eventi di sistema e 
di widget (diversi da quelli previsti negli eventi resi pubblici dei componenti CLX), 
vedere "Risposta alle notifiche di sistema utilizzando la CLX" a pagina 51-11. 



Condivisione di file sorgente tra Windows e Linux 



Se si desidera che l'applicazione sia eseguita sia in Windows che in Linux, e possibile 
condividere i file sorgente rendendoli accessibili a entrambi i sistemi operativi. E 
possibile fare cio in molti modi, come, ad esempio, mettendo i file sorgente su un 
server accessibile a entrambi i computer oppure utilizzando Samba sulla macchina 
Linux per consentire l'accesso ai file mediante la condivisione di file in rete Microsoft 
sia per Linux che per Windows. E possibile decidere di tenere i sorgenti su Linux e 
creare un'unita condivisa su Linux. Oppure e possibile tenere i sorgenti su Windows 
e creare una condivisione in Windows affinche la macchina Linux possa accedervi. 

E possibile continuare a sviluppare e compilare il file su C++Builder utilizzando 
oggetti supportati sia dalla VCL sia dalla CLX. Una volta terminate, e possibile 
compilare su Windows. Appena sara disponibile una soluzione C++ per Linux sara 
possibile eseguire la compilazione in Linux. 

Se si crea una nuova applicazione CLX, in C++Builder viene creato un file .xfm 
invece di un file .dfm. 



Differenze di ambiente fra Windows e Linux 



Attualmente, il termine multipiattaforma sta ad indicare un' applicazione che puo 
essere eseguita, praticamente senza modifiche, su entrambi i sistemi operativi 
Windows e Linux. La seguente tabella elenca alcune differenze esistenti fra gli 
ambienti operativi Linux e Windows. 

Tabella 14.7 Differenze fra gli ambienti operativi Linux e Windows 
Differenze Descrizlone 



Sensibilita alle 
maiuscole/minuscole nei 
nomi di file 

Caratteri di fine riga 



Carattere di fine file 



Batch file/ procedure di 
shell 



In Linux, i nomi dei file risentono delle differenze fra maiuscole e 
minuscole. II file Test.txt e un file differente rispetto al file test.txt. In 
Linux e necessario prestare grande attenzione all'uso delle 
maiuscole/ minuscole nei nomi dei file. 

In Windows, le righe di testo terminano con CR/LF (cioe, ASCII 13 + 
ASCII 10), mentre in Linux viene usato solo LF. Benche l'editor di 
codice sia in grado di gestire la differenza, e bene ricordarsene 
quando si importa del codice in Windows. 

In MS-DOS e in Windows, il carattere con valore #26 (Ctrl-Z) viene 
trattato come la fine del file di testo, anche se, dopo quel carattere, nei 
file vi sono dati. Linux utilizza Ctrl+D come carattere di fine file. 

L'equivalente Linux dei file .bat sono le procedure di shell. Una 
procedura e un file di testo contenente istruzioni, salvate e rese 
eseguibile con il comando, chrnod +x <scriptfile>. II linguaggio 
procedurale dipende dalla shell utilizzata su Linux. Bash e quello 
usato piu di frequente. 
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Tabella 14.7 Differenze fra gli ambienti operativi Linux e Windows 
Differenze Descrizione 



Conferma dei comandi 



Risultato dei comandi 
Parametri dei comandi 

File di configurazione 



DLL 

Lettere di unita 

Eccezioni 
File eseguibili 

Estensioni dei nomi di file 

Permessi sui file 



In MS-DOS o in Windows, se si prova a cancellare un file o una 
cartella, apparira una richiesta di conferma (un messaggio del tipo "Si 
conferma l'operazione?"). Di solito, Linux non fa alcuna domanda; 
eseguira l'ordine o il comando. In questo modo e molto facile 
distruggere casualmente un file o l'intero file system. In Linux non c'e 
alcun modo per annullare una cancellazione a meno che non sia stata 
fatta una copia di riserva del file su altro supporto. 

In Linux, se un comando va a buon fine, viene rivisualizzato il prompt 
dei comandi senza alcun messaggio di stato. 

Linux utilizza un trattino (-) per indicare un parametro di comando o 
un trattino doppio (— ) per piii caratteri di opzioni mentre il DOS 
utilizza una barra (/) o un trattino (-). 

In Windows, la configurazione viene fatta nel file di registro o in file 
come autoexec.bat. 

In Linux, i file di configurazione vengono creati come file nascosti 
nella directory home dell'utente. I file di configurazione presenti nella 
directory / etc di solito non sono nascosti. 

Linux utilizza anche variabili di ambiente come LD_LIBRARY_PATH 
(percorso di ricerca per le librerie). Altre variabili di ambiente 
importanti: 

HOME La directory iniziale dell'utente (/home/ sam) 
TERM Tipo di terminale (xterm, vtlOO, console) 
SHELL percorso per la shell (/bin/bash) 
USER II nome di login dell'utente (sfuller) 
PATH Elenco di ricerca dei programmi 

Queste variabili sono specificate nella shell o nei file come ad esempio 
.bashrc. 

Su Linux, si utilizzano file di oggetti condivisi (.so). I corrispondenti 
Windows sono le librerie a collegamento dinamico (DLL). 

Linux non ha lettere di unita. Un esempio di percorso Linux e /lib/ 
security. Fare riferimento a DriveDelim nella libreria di runtime. 

Le eccezioni di sistema operativo in Linux vengono chiamate segnali. 

In Linux, i file eseguibili non richiedono alcuna estensione. In 
Windows, i file eseguibili hanno l'estensione exe. 

Linux non utilizza estensioni dei nomi di file per identificare i tipi di 
file o per associare i file alle applicazioni. 

In Linux, ai file (e alle directory) vengono assegnati i diritti di lettura, 
scrittura ed esecuzione al proprietario di file, al gruppo e ad altri. Ad 
esempio, -rwxr-xr-x significa, da sinistra a destra: 

- e il tipo di file (- = file comune, d = directory, 1 = collegamento); rwx 
sono i permessi concessi al proprietario del file (lettura, scrittura, 
esecuzione); r-x sono i permessi concessi al gruppo del proprietario 
del file (lettura, esecuzione); e r-x sono i permessi concessi a tutti gli 
altri utenti (lettura, esecuzione). L'utente root (superuser) pud 
ridefinire questi permessi. 

E necessario accertarsi che l'applicazione venga eseguita dall'utente 
corretto e abbia i corretti accessi per i file necessari. 
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Tabella 14.7 Differenze fra gli ambienti operativi Linux e Windows 
Differenze Descrizione 



Programma di utilita 
Make 



Multitasking 



Percorsi 



Percorsi di ricerca 



Separatore del percorso di 
ricerca 

Collegamenti simbolici 



II programma di utilita Make di Borland non e disponibile sulla 
piattaforma Linux. Al suo posto e possibile utilizzare il programma di 
utilita Make GNU proprio di Linux. 

Linux supporta completamente il multitasking. E possibile eseguire 
contemporaneamente svariati programmi (in Linux, vengono 
chiamati processi). E possibile avviare processi in background 
(utilizzando il simbolo & dopo il comando) e continuare a operare 
tranquillamente. Linux consente anche di avere diverse sessioni. 

Linux utilizza una barra (/) mentre il DOS utilizza una barra 
retroversa (\). Per specificare il carattere appropriato per la 
piattaforma e possibile utilizzare la costante PathDelim. Fare 
riferimento a PathDelim nella libreria di runtime. 

Per 1'esecuzione dei programmi, Windows controlla sempre, come 
prima cosa, la directory corrente, quindi guarda nei percorsi 
specificati nella variabile di ambiente PATH. Linux non guarda mai 
nella directory corrente ma cerca soltanto nelle directory elencate in 
PATH. Per eseguire un programma nella directory corrente, di solito 
e necessario immettere il carattere ./ prima del nome del programma. 

E possibile anche modificare la variabile PATH in modo da includere 
./ come primo percorso di ricerca. 

Windows utilizza il punto e virgola come separatore dei percorsi di 
ricerca. Linux utilizza il carattere due punti. Fare riferimento a 
PathDelim nella libreria di runtime. 

Su Linux, un collegamento simbolico e un file speciale che punta a un 
altro file su disco. Se si collocano i collegamenti simbolici nella 
directory globale bin che punta ai file principali dell'applicazione non 
sara necessario modificare il percorso di ricerca di sistema. Un 
collegamento simbolico viene creato con il comando In (link). 

Windows ha i collegamenti del desktop. Di solito, per rendere un 
programma disponibile dalla riga comandi, i programmi di 
installazione Windows modificano il percorso di ricerca di sistema. 



Struttura delle directory su Linux 

In Linux le directory sono diverse. Qualsiasi file o dispositivo puo essere montato 
ovunque nel file system. 

I nomi dei percorsi in Linux utilizzano le barre diritte mentre i nomi dei percorsi in 
Windows utilizzano le barre retroverse. La barra iniziale indica la directory radice. 

Di seguito sono elencate alcune directory comunemente utilizzate in Linux. 

Tabella 14.8 Directory Linux comuni 
Directory Contentuto 

/ La directory radice o superiore dell'intero file system Linux 

/ root La radice del file system; la home directory del Superuser 

/bin Comandi, programmi di utilita 
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Tabella 14.8 Directory Linux comuni (continua) 



Directory Contentuto 

/ sbin Programmi di utilita di sistema 

/ dev Dispositivi visualizzati come file 

/lib Librerie 

/home/ username File di proprieta dall'utente in cui username e il nome del login 
dell'utente. 

/ opt Accessori 

/boot Kernel che viene chiamato all'avvio del sistema 

/ etc File di configurazione 

/ usr Applicazioni, programmi. Di solito include directory come / usr/ spool, / 
usr/man, /usr/include, / usr/local 

/ mnt Altri supporti montati sul sistema come un CD o un'unita per dischetti 

/ var File di registrazione, messaggi, file di spool 

/ proc Statistiche del file system virtuale e del sistema di reporting 

/ tmp File temporanei 



Le varie distribuzioni di Linux collocano talvolta i file in posizioni differenti. Un 
programma di utilita potrebbe essere collocato in /bin da una distribuzione Red Hat 
e collocato invece in /usr/local/bin da una distribuzione Debian. 

Consultare www.pathname.com per ulteriori dettagli sull'organizzazione del file 
system gerarchico dell'ambiente UNIX/Linux e leggere il documento Filesystem 
Hierarchy Standard. 

Scrittura di codice portabile 



Se si stanno scrivendo applicazioni multipiattaforma destinate a funzionare in 
Windows e in Linux, e possibile scrivere del codice che venga compilato in base a 
diverse condizioni. Utilizzando la compilazione condizionale, e possibile conservare 
la codifica Windows consentendo al contempo le differenze dovute al sistema 
operativo Linux. 

Per creare applicazioni che siano facilmente portabili tra Windows e Linux, e bene 
ricordare di: 

• ridurre o isolare le chiamate alle API specif iche della piattaforma (Win32 o Linux); 
utilizzare invece i metodi della CLX oppure chiamate alia libreria QT. 

• eliminare dall'applicazione i costrutti relativi alia gestione dei messaggi Windows 
(PostMessage, SendMessage). In CLX, chiamare invece i metodi 
QApplication_postEvent e QApplication_sendEvent. Per informazioni sulla scrittura 
di componenti che rispondono a eventi di sistema e di widget, consultare 
"Risposta alle notifiche di sistema utilizzando la CLX" a pagina 51-11. 

• utilizzare TMemlniFile invece di TReglniFile. 

• osservare e proteggere l'utilizzo di maiuscole/ minuscole nei nomi di file e di 
directory. 
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• Fare il porting di tutto il codice TASM prodotto dall'assembler esterno. 

L'assembler GNU, "as," non supporta la sintassi TASM. (Vedere "Inclusione di 
codice assembler in linea" a pagina 14-20.) 

Provare a scrivere il codice utilizzando le routine di libreria runtime indipendenti 
dalla piattaforma e le costanti incluse in System, SysUtils e in altre unit della libreria 
runtime. Ad esempio, utilizzare la costante PathDelim per isolare quelle parti di 
codice che, a seconda della piattaforma, utilizzano la barra / al posto della barra 
retroversa. 

Un altro esempio riguarda l'utilizzo di caratteri multibyte su entrambe le 
piattaforme. II codice Windows normalmente si aspetta solo due byte per ogni 
carattere multibyte. In Linux, la codifica dei caratteri multibyte puo richiedere molti 
piu byte per carattere (fino a sei byte per UTF-8). Entrambe le piattaforme possono 
essere gestite utilizzando la funzione StrNextChar in SysUtils. Del codice Windows 
come quello che segue 

while (*p != 0) 

{ 

if (LeadBytes .Contains (*p) ) 

P++; 
P++; 

} 

puo essere sostituito con del codice indipendente dalla piattaforma simile al 
seguente: 

while (*p != 0) 

{ 

if (LeadBytes .Contains (*p) ) 

p = StrNextchar (p) ; 
else 

P++; 

} 

Questo esempio e portabile su piu piattaforme, ma tuttavia non consente di evitare 
ancora il costo, in termini di prestazioni, a una chiamata di procedura per ambienti 
non-multibyte. 

Se l'utilizzo di funzioni di libreria di esecuzione non e una soluzione adottabile, 
provare a isolare il codice specifico per la piattaforma presente nella routine in un 
pezzo o in una subroutine. Provare a limitare il numero di blocchi #if def per 
conservare la leggibilita e la portability del codice sorgente. II simbolo condizionale 
WIN32 non e definito in Linux. II simbolo condizionale LINUX e definite e indica 
che il codice sorgente viene compilato per la piattaforma Linux. 

Utilizzo delle direttive condizionali 

L'uso di direttive di compilazione #ifdef e un metodo accettabile per condizionare il 
codice in funzione delle piattaforme Windows e Linux. Tuttavia, poiche le direttive 
#ifdef rendono il codice sorgente piu difficile da capire e da mantenere, e necessario 
capire quando e accettabile utilizzare le direttive di #if def . Se si presentasse 
l'occasione di utilizzare la direttiva #ifdef, le domande che ci si dovrebbero porre 
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sono "Perche questo codice richiede un #if def ?" e "Puo essere scritto senza un 
#ifdef?" 

Per l'utilizzo di #if def all'interno di applicazioni multipiattaforma, seguire queste 
regole generali: 

• Provare a non utilizzare #ifdef a meno che non sia assolutamente necessario. Le 
direttive #ifdef in un file sorgente vengono valutate solo al momento della 
compilazione del codice sorgente. C / C++ necessitano dei sorgenti della unit (file 
header) per compilare un progetto. La rigenerazione completa di tutto il codice 
sorgente e un evento insolito per la maggior parte dei progetti C++Builder. 

• Non utilizzare #ifdef nei file package (.bpk). Limitare il loro utilizzo ai file 
sorgente. Gli scrittori di componenti devono creare due package distinti di 
progettazione quando sviluppano per piu piattaforme, e non un solo package 
utilizzando #ifdef . 

• In generale, utilizzare #if def WINDOWS per verificare tutte le piattaforme 
Windows, inclusa WIN32. Riservare l'utilizzo di #ifdef WIN32 per effettuare una 
distinzione fra piattaforme Windows specifiche, ad esempio tra Windows 32 bit e 
64 bit. Non limitare il codice alia piattaforma WIN32 a meno che non si sappia per 
certo che non verra utilizzato in WIN64. 

• Evitare test di negazione come #ifndef a meno che non sia assolutamente 
necessario. #ifndef linux non e equivalente a #ifdef WINDOWS. 

• Evitare combinazioni #ifndef/#else. Utilizzare invece un test positivo (#ifdef) per 
migliorare la leggibilita. 

• Evitare clausole #else in #ifdef sensibili alia piattaforma. Usare blocchi #ifdef 

separati per Linux e codice specifico per Windows al posto di #if def linux / 

#else oppure di #ifdef WINDOWS/#else. 

Ad esempio, del vecchio codice potrebbe contenere 

#ifdef WIN32 

(32-bit Windows code) 
Seise 

(16-bit Windows code) //!! By mistake, Linux could fall into this code. 
#endif 

Per qualsiasi codice non portatile in #ifdef, e preferibile che il codice sorgente non 
venga compilato piuttosto che la piattaforma utilizzi erroneamente una clausola 
#else e generi misteriosamente un errore in esecuzione. Gli errori di compilazione 
sono piu facili da individuare dei malfunzionamenti in esecuzione. 

• Utilizzare la sintassi #if per test complicati. Sostituire #if def annidati con 
un'espressione booleana in una direttiva #if . Si deve terminare la direttiva #if 
usando #endif . Cio consente di collocare espressioni #if all'interno di direttive 
#ifdef in modo da nascondere la nuova sintassi #if ai compilatori precedenti. 

Tutte le direttive condizionali sono documentate nella Guida in linea. Per ulteriori 
informazioni, consultare anche l'argomento "Conditional Compilation" nella Guida 
in linea. 
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Emissione di messaggi 

La direttiva al compilatore #pragma consente al codice sorgente di emettere 
suggerimenti e avvertimenti ed errori, esattamente come il compilatore. Usare la 
direttiva #pragma messaggio per specificare all'interno del codice del programma un 
messaggio definito dall'utente, utilizzando uno dei formati indicati di seguito. 

Se vi e un numero variabile di costanti di stringa, utilizzare: 

♦pragma message! "hi there" ) 
♦pragma message! "hi" " there" ) 

Per scrivere del testo dopo un messaggio, utilizzare: 

tpragma message text 

Per espandere un valore definito in precedenza, utilizzare: 

tpragma message (text) 

♦define text "a test string" 
♦pragma message (text) 

Ad esempio, per visualizzare questi messaggi su un pulsante, utilizzare: 

void __fastcall TForml: :ButtonlClick(TObject *Sender) 
{ 

♦pragma message! "hi there 1" ) 
♦pragma message ( "hi * "there 2" ) 

♦pragma message hi there 3 

♦define text "a test string" 
♦pragma message (text) 

} 

Per visualizzare i messaggi nell'IDE, sceglire il comando Projects I Options I 
Compiler, fare clic sulla pagina Compiler e selezionare la casella di controllo Show 
general messages. 

Inclusione di codice assembler in linea 

Se nelle applicazioni Windows si include del codice assembler in linea, potrebbe non 
essere possibile utilizzare lo stesso codice in Linux a causa dei requisiti PIC position- 
independent code (PIC) su Linux. Le librerie di oggetti condivisi di Linux 
(equivalenti alle DLL) richiedono che tutto il codice sia rilocabile in memoria senza 
modifiche. Cio influisce principalmente sulle routine assembler in linea che 
utilizzano variabili globali o altri indirizzi assoluti oppure che chiamano funzioni 
esterne. 

Per le unit che contengono solo codice C++, se necessario, il compilatore genera 
automaticamente codice PIC. E buona norma compilare ogni file sorgente in 
entrambi i formati PIC e non-PIC; utilizzare il parametro -VP del compilatore per 
generare codice PIC. 

Si potrebbe voler scrivere le routine assembler in modo diverso a seconda che si stia 
compilando un eseguibile o una libreria condivisa; utilizzare la direttiva 
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#ifdef PIC per dividere in due sezioni distinte le due diverse versioni del codice 

assembler. Oppure, per evitare il problema, si potrebbe riscrivere la routine in C++. 

Di seguito sono riportate le regole PIC per il codice assembler in linea: 

• PIC richiede che tutti i riferimenti di memoria siano fatti rispetto al registro EBX, 
che contiene il puntatore all'indirizzo di base del modulo corrente (in Linux viene 
chiamato Global Offset Table o GOT). Pertanto, invece di 

MOV EAX.GlobalVar 

utilizzare 

MOV EAX, [EBX] .GlobalVar 

• PIC richiede che il registro EBX venga protetto durante le varie chiamate delle 
istruzioni in linguaggio macchina (come in Win32), e inoltre che il registro EBX 
venga ripristinato prima di effettuare chiamate a funzioni esterne (diversamente 
da Win32). 

• Benche il codice PIC funzioni negli eseguibili di base, potrebbe pero diminuire le 
prestazioni e generare molto codice. Negli oggetti condivisi non vi sono 
alternative, ma negli eseguibili si vorranno probabilmente ottenere le migliori 
prestazioni possibili. 

Differenze di programmazione in Linux 



II widechar wchar_t di Linux e pari a 32 bit per carattere. Lo standard a 16 bit 
Unicode supportato dalla VCL e dalla CLX e un sottoinsieme dello standard UCS a 
32 bit supportato da Linux e dalle librerie GNU. I tipi WideString devono essere 
espansi a 32 bit per carattere prima di poterli passare a una funzione del sistema 
operativo come wchar_t. 

In Linux, i tipi WideStrings vengono conteggiati per riferimento analogamente ai tipi 
long string (a differenza di Windows). 

In Windows, i caratteri multibyte (MBCS) sono rappresentati come codici di carattere 
a uno e a due byte. In Linux, vengono rappresentati da uno a sei byte. 

AnsiStrings e in grado di gestire sequenze di caratteri multibyte, dipendenti dalle 
impostazioni dell'ambiente dell'utente. La codifica Linux per caratteri multibyte 
come il giapponese, il cinese, l'ebraico e l'arabo potrebbe non essere compatibile con 
la codifica Windows per lo stesso ambiente. Unicode e portatile, mentre multibyte 
non lo e. Per i dettagli sulla gestione delle stringhe per le diverse impostazioni locali 
nelle applicazioni internazionali, consultare "Abilitazione del codice 
dell'applicazione" a pagina 16-2. 

Applicazioni database multipiattaforma 



In Windows, C++Builder offre diverse possibility per accedere alle informazioni di 
database. Queste includono l'utilizzo di ADO, di BDE (Borland Database Engine) e di 
InterBase Express. In Windows e Linux e possibile utilizzare dbExpress, una 



Sviluppo di applicazioni multipiattaforma 14-21 



Applicazioni database multipiattaforma 

tecnologia multipiattaforma per l'accesso ai dati, a seconda della versione di 
C++Builder che si posside. 

Prima di fare il porting un'applicazione database in dbExpress in modo che possa 
essere eseguita in Linux, si dovrebbero capire le differenze fra l'utilizzo di dbExpress e 
il meccanismo di accesso di dati utilizzato in precedenza. Queste differenze si 
verificano a vari livelli. 

• Al livello piu basso, c'e uno strato che comunica tra l'applicazione e il server di 
database. Questo potrebbe essere ADO, BDE o il software InterBase client. Questo 
strato e sostituito da dbExpress, che e un gruppo di driver leggeri per 
l'elaborazione dinamica di SQL. 

• L'accesso ai dati di basso livello e incluso in un set di componenti che vengono 
aggiungono ai moduli dati o alle schede. Questi componenti includono i 
componenti per la connessione ai database, che rappresentano la connessione a un 
server di database e i dataset, che rappresentano i dati prelevati dal server. Benche 
vi siano alcune differenze molto importanti, dovute alia natura unidirezionale di 
cursor di dbExpress, le differenze sono meno pronunciate a questo livello, poiche i 
dataset condividono tutti un antenato comune, come del resto anche i componenti 
per la connessione ai database. 

• A livello interfaccia utente, vi sono ancor meno differenze. I controlli data-aware 
CLX sono progettati per essere il piu simile possibile ai corrispondenti controlli 
Windows. Le differenze principali a livello di interfaccia utente derivano dalle 
modifiche necessarie per gestire l'utilizzo degli aggiornamenti in cache. 

Per informazioni sul porting di applicazioni database esistenti in dbExpress, 
consultare "Porting di applicazioni database in Linux" a pagina 14-25. Per 
informazioni sulla progettazione di nuove applicazioni dbExpress, vedere il Capitolo 
18, "Progettazione di applicazioni database". 

Differenze in dbExpress 



In Linux, dbExpress gestisce la comunicazione con i server di database. dbExpress e 
formato da un gruppo di driver leggeri che implementano un insieme di interfacce 
comuni. Ogni driver e un oggetto condiviso (file .so) di cui si deve eseguire il link 
nell'applicazione. Poiche dbExpress e progettato per essere multipiattaforma, e 
disponibile anche in ambiente Windows come un insieme di librerie a collegamento 
dinamico (.dll). 

Come qualsiasi altro strato per l'accesso ai dati, anche dbExpress richiede un software 
sul lato client fornito dal produttore di database. Inoltre, utilizza un driver specifico 
per il database, piu due file di configurazione, dbxconnections e dbxdrivers. Questo e 
notevolmente meno di quanto sia necessario, ad esempio, per BDE, che richiede la 
libreria principale di Borland Database Engine (Idapi32.dll) oltre a un driver specifico 
per il database e a molte altre librerie di supporto. 

Inoltre, dbExpress: 
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• consente un percorso piu semplice e piu rapido per accedere ai database remoti. 
Di conseguenza e lecito aspettarsi un incremento di prestazioni notevole nel caso 
di un accesso semplice e diretto ai dati. 

• e in grado di elaborare le query e le procedure registrate, ma non supporta il 
concetto dell'apertura di tabelle. 

• restituisce solo cursori unidirezionali. 

• non dispone di un supporto interno per l'aggiomamento, se si esclude la capacita 
di eseguire una query INSERT, DELETE o UPDATE. 

• non e in grado di collocare in cache i metadati, e l'interfaccia per l'accesso ai 
metadati in fase di progettazione e implementata utilizzando l'interfaccia di base 
per l'accesso ai dati. 

• esegue solo le query richieste dall'utente, ottimizzando pertanto l'accesso al 
database dal momento che non vengono introdotte ulteriori query. 

• gestisce internamente un buffer per i record o un blocco di buffer per i record. 
Questo comportamento e diverso rispetto a BDE, in cui sono i client a dover 
allocare la memoria utilizzata per memorizzare record. 

• supporta solo tabelle locali basate su SQL, come InterBase e Oracle. 

• utilizza i driver per DB2, Informix, InterBase, MySQL e Oracle. Se si utilizza un 
server di database diverso, e necessario convertire i dati in uno di questi formati di 
database, oppure scrivere un driver dbExpress appositamente per il server di 
database utilizzato oppure, ancora, ottenere un driver dbExpress di terze parti per 
il server di database. 



Quando si scrive un'applicazione con dbExpress, e necessario utilizzare un set di 
componenti per l'accesso ai dati diverso da quello utilizzato nelle applicazioni 
database esistenti. I componenti dbExpress condividono le stesse classi di base di altri 
componenti per l'accesso ai dati (TDataSet e TCustomConnection), il che significa che 
molte proprieta, metodi ed eventi sono identici a quelli dei componenti utilizzati 
nelle applicazioni esistenti. 

La Tabella 14.9 elenca i principali componenti database utilizzati con InterBase 
Express, BDE e ADO in ambiente Windows e mostra gli analoghi componenti 
dbExpress da utilizzare in Linux e in applicazioni multipiattaforma. 

Tabella 14.9 Componenti paragonabili per l'accesso ai dati 



Differenze a livello di componenti 



Componenti 

InterBase Express Componenti BDE Componenti ADO 

TIBDatabase TDatabase TADOConnection 



Componenti dbExpress 

TSQLConnection 

TSQLTable 

TSQLQuery 

TSQLStoredProc 

TSQLDataSet 



TIBTable 



TTable 



TADOTable 



TIBQuery 
TIBStoredProc 



TQuery 
TStoredProc 



TADOQuery 
TADOStoredProc 



TIBDataSet 



TADODataSet 
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I componenti dataset dbExpress (TSQLTable, TSQLQuery, TSQLStoredProc e 
TSQLDataSet) sono piu limitati dei componenti corrispondenti, in quanto non 
supportano l'editing e consentono solo lo spostamento in avanti. Per ulteriori 
informazioni sulle differenze tra i dataset dbExpress e gli altri dataset disponibili in 
Windows, consul tare il Capitolo 26, "Uso di dataset unidirezionali". 

A causa della mancanza di supporto per l'editing e la navigazione, la maggior parte 
delle applicazioni dbExpress non operano direttamente con i dataset dbExpress. Tali 
applicazioni connettono, invece, il dataset dbExpress a un dataset client, che 
memorizza i record in memoria e fornisce il supporto per l'editing e la navigazione. 
Per ulteriori informazioni su questa architettura, consultare "Architettura di un 
database" a pagina 18-6. 

Per applicazioni molto semplici, e possibile utilizzare TSQLClientDataSet invece di un 
dataset dbExpress connesso a un dataset client. Questo presenta il vantaggio della 
semplicita, in quanto esiste una corrispondenza 1:1 tra il dataset nell'applicazione di 
cui si sta facendo il porting e il dataset nell'applicazione convertita, ma risulta meno 
flessibile rispetto alia connessione esplicita di un dataset dbExpress a un dataset client. 
Per la maggior parte delle applicazioni, si consiglia di utilizzare un dataset dbExpress 
connesso a un componente TClientDataSet. 

Differenze a livedo di interfaccia utente 



I controlli data-aware CLX sono progettati per essere il piu simile possibile ai 
corrispondenti controlli Windows. Di conseguenza, il porting dell'interfaccia utente 
delle applicazioni database richiede poche considerazioni aggiuntive oltre a quelle 
normalmente implicate nel porting in CLX di una qualsiasi applicazione Windows. 

Le principali differenze a livello di interfaccia utente derivano dalle differenze nel 
modo in cui i dataset dbExpress o i dataset client forniscono dati. 

Se si utilizzano solo dataset dbExpress, e necessario adattare l'interfaccia utente per 
gestire il fatto che i dataset non supportano l'editing e supportano solo lo 
spostamento in avanti all'interno del dataset. Pertanto, ad esempio, potrebbe essere 
necessario rimuovere i controlli che consentono all'utente di passare a un record 
precedente. Poiche i dataset dbExpress non hanno un buffer per i dati, e impossibile 
visualizzare i dati in una griglia data-aware: e possibile visualizzare solo un record 
alia volta. 

Se invece si connette il dataset dbExpress a un dataset client, gli elementi 
dell'interfaccia utente associati alle funzioni di editing e di navigazione dovrebbero 
ancora funzionare. Sara solo necessario riconnetterli al dataset client. La 
considerazione principale in questo caso e la gestione della modalita di scrittura nel 
database degli aggiornamenti. Per impostazione predefinita, la maggior parte dei 
dataset in ambiente Windows scrive automaticamente gli aggiornamenti nel server 
di database non appena vengono confermati (ad esempio, quando l'utente si sposta 
su un nuovo record). I dataset client, d'altro canto, conservano sempre gli 
aggiornamenti nella cache in memoria. Per informazioni su come gestire queste 
differenze, consultare "Aggiornamento dei dati in applicazioni dbExpress" a 
pagina 14-28. 
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Porting di applicazioni database in Linux 



II porting di un'applicazione database in dbExpress consente di creare 
un'applicazione della piattaforma che potra essere eseguita sia in Windows sia in 
Linux. II processo di porting implica alcune modifiche all'applicazione perche la 
tecnologia e differente. II grado di difficolta del porting dipendera dal tipo di 
applicazione, dalla sua complessita e dalle operazioni che dovra compiere. II porting 
di un'applicazione che utilizza pesantemente le tecnologie specifiche di Windows, 
come ADO, sara piu difficile di quello di un'applicazione che utilizza la tecnologia 
database di C++Builder. 

Per eseguire il porting di un'applicazione database Windows /VCL in Linux/ CLX, 
seguire queste direttive generali: 

1 Assicurarsi che i dati siano memorizzati in un database supportato da dbExpress, 
come DB2, Informix, InterBase, MySQL e Oracle. I dati devono risiedere in uno di 
questi server SQL. Se i dati non sono gia memorizzati in uno di questi database, 
trovare un programma di utilita per effettuarne la conversione. 

Ad esempio, e possibile utilizzare il programma di utilita Data Pump di 
C++Builder (non disponibile in tutte le versioni) per convertire alcuni database 
(come dBase, FoxPro e Paradox) in un database supportato da dbExpress. (Per 
informazioni sull'utilizzo del programma di utilita, consultare il file 
datapump.hlp in Program FilesXCommon Files\Borland\Shared\BDE.) 

2 Creare moduli dati che contengano i dataset e i componenti connection in modo 
che risultino separati dalle schede e dai componenti dell'interfaccia utente. In 
questo modo, si isolano in moduli dati appositi da quelle parti dell'applicazione 
che richiedono un set completamente nuovo di componenti. Le schede che 
rappresentano l'interfaccia utente possono essere quindi convertite come una 
qualsiasi altra applicazione. Per i dettagli, consultare "Porting dell'applicazione" a 
pagina 14-3. 

Le fasi rimanenti partono dal presupposto che i dataset e i componenti connection 
siano stati isolati nei rispettivi moduli dati. 

3 Creare un nuovo modulo dati per contenere le versioni CLX dei componenti 
dataset e connection. 

4 Per ogni dataset nell'applicazione originale, aggiungere un dataset dbExpress, un 
componente TDataSetProvider e un componente TClientDataSet. Utilizzare le 
corrispondenze nella Tabella 14.9 per decidere quale dataset dbExpress utilizzare. 
Assegnare a questi componenti nomi significativi. 

• Impostare la proprieta ProviderName del componente TClientDataSetal nome 
del componente TDataSetProvider. 

• Impostare la proprieta DataSet del componente TDataSetProvideral dataset 

dbExpress. 

• Modificare la proprieta DataSet di qualsiasi componente datasource che faceva 
riferimento al dataset originale in modo che faccia riferimento al dataset client. 
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5 Impostare le proprieta del nuovo dataset in modo che corrispondano al dataset 
originale: 

• Se il dataset originale era un componente TTable, TADOTableo TIBTable, 
impostare la nuova proprieta TableNamedel componente TSQLTable al valore 
di TableName del dataset originale. Copiare inoltre tutte le proprieta utilizzate 
per impostare relazioni master/detail o per specificare indici. Le proprieta 
utilizzate per specificare intervalli e filtri dovrebbero essere impostate sul 
dataset client invece che sul nuovo componente TSQLTable. 

• Se il dataset originale era un componente TQuery, TADOQueryo TIBQuery, 
impostare la proprieta SQL del nuovo componente TSQLQuery alia proprieta 
SQL del dataset originale. Impostare la proprieta Params del nuovo TSQLQuery 
in modo che corrisponda al valore della proprieta Params o Parameters del 
dataset originale. Se era stata impostata la proprieta DataSource per stabilire una 
relazione un master/ detail, copiare anche questa. 

• Se il dataset originale era un componente TStoredProc, TADOStoredProco 
TIBStoredProc, impostare la proprieta StoredProcName del nuovo componente 
TSQLStoredProc alia proprieta StoredProcNameo ProcedureName del dataset 
originale. Impostare la proprieta Params del nuovo TSQLStoredProc in modo che 
corrisponda al valore della proprieta Params o Parameters del dataset originale. 

6 Per ogni componente connection nell'applicazione originale (TDatabase, 
TIBDatabase o TADOConnection), aggiungere al nuovo modulo dati un 
componente TSQLConnection. E necessario anche aggiungere un componente 
TSQLConnection per ogni server di database a cui ci si collegava senza utilizzare 
uno specifico componente connection (ad esempio, utilizzando la proprieta 
ConnectionString di un dataset ADO o impostando la proprieta DatabaseName di un 
dataset BDE a un alias BDE). 

7 Per ogni dataset dbExpress collocato al punto 4, impostare la rispettiva proprieta 
SQLConnection al componente TSQLConnection che corrisponde alia connessione 
database appropriata. 

8 In ogni componente TSQLConnection, specificare le informazioni necessarie per 
stabilire una connessione al database. Per fare cid, fare doppio clic sul componente 
TSQLConnection per visualizzare il Connection Editor e impostare valori del 
parametro in modo da indicare le impostazioni appropriate. Se al punto 1 e stato 
necessario trasferire i dati in un nuovo server di database, allora e necessario 
specificare le impostazioni appropriate al nuovo server. Se si sta utilizzando lo 
stesso server usato in precedenza, e possibile cercare alcune di queste 
informazioni sul componente connection originale: 

• Se l'applicazione originale utilizzava TDatabase, e necessario trasferire le 
informazioni contenute nelle proprieta Params e Translsolation. 

• Se l'applicazione originale utilizzava TADOConnection, e necessario trasferire le 
informazioni contenute nelle proprieta ConnectionString e IsolationLevel. 

• Se l'applicazione originale utilizzava TIBDatabase, e necessario trasferire le 
informazioni contenute nelle proprieta DatabaseName e Params. 
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• Se in origine non c'era alcun componente connection, e necessario trasferire le 
informazioni associate all'alias BDE o cio che era contenuto nella proprieta 
ConnectionString del dataset. 

Si potrebbe decidere di salvare questo set di parametri con un nuovo nome di 
connessione. Per maggiori informazioni su questa operazione, consultare 
"Controllo delle connessioni" a pagina 21-3. 
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Aggiornamento dei dati in applicazioni dbExpress 



Le applicazioni dbExpress utilizzano i dataset client per supportare l'editing. Quando 
si confermano le modifiche in un dataset client, le modifiche vengono scritte nella 
copia dei dati residente in memoria del dataset client ma non vengono riportate 
automaticamente nel server di database. Se l'applicazione originate utilizzava un 
dataset client per memorizzare gli aggiornamenti nella cache, non e necessario 
modificare alcunche per supportare l'editing in Linux. Tuttavia, se si faceva 
affidamento sul comportamento predefinito della maggior parte dei dataset in 
Windows, che e quello di scrivere le modifiche nel server di database nel momento in 
cui vengono confermate, sara necessario apportare delle modifiche per gestire 
l'utilizzo di un dataset client. 

Esistono due modi per convertire un'applicazione che in precedenza non 
memorizzava gli aggiornamenti nella cache: 

• possibile imitare il comportamento del dataset in Windows scrivendo del codice 
per applicare ogni record aggiornato al server di database non appena viene 
confermato. Per fare cio, fornire al dataset client un gestore di evento AfterPost in 
grado di applicare gli aggiornamenti al server di database: 

void __fastcall TForml: :ClientDataSetlAfterPost (TDataSet *DataSet) 

{ 

TClientDataSet *pCDS = dynamic_cast<TClientDataSet *>(DataSet) ; 
if (pCDS) 
pCDS->ApplyUpdates (1) ; 

} 

• E possibile adattare l'interfaccia utente in modo che si occupi degli aggiornamenti 
in cache. Questo approccio presenta alcuni vantaggi, come la riduzione delle 
quantita di traffico di rete e la riduzione dei tempi di transazione. Tuttavia, se si 
passa all'utilizzo di aggiornamenti in cache, occorre decidere quando applicare 
quegli aggiornamenti al server di database e probabilmente apportare delle 
modifiche all'interfaccia utente per consentire agli utenti di iniziare l'applicazione 
degli aggiornamenti o per informarli se le modifiche apportate sono stato 
registrate nel database. Inoltre, poiche quando l'utente invia un record gli errori di 
aggiornamento non vengono rilevati, sara necessario modificare il modo in cui 
vengono segnalati tali errori all'utente, affinche possano vedere non solo quale 
aggiornamento ha causato un problema ma anche che tipo di problema si e 
verificato. 

Se l'applicazione originale utilizzava il supporto fornito da BDE o da ADO per 
aggiornamenti in cache, sara necessario apportare alcune modifiche nel codice per 
passare all'utilizzo di un dataset client. La tabella seguente elenca proprieta, eventi e 
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metodi che supportano gli aggiornamenti in cache con i dataset BDE e ADO e 
proprieta, metodi ed eventi corrispondenti nei TClientDataSet: 

Tabella 14.10Proprieta , metodi ed eventi degli aggiornamenti in cache 
Nei dataset BDE 

(o TDatabase) Nei dataset ADO In TClientDataSet Funzione 



CachedUpdates 



LockType 



Non supportato CursorType 



Non necessario, i 
dataset client 
memorizzano 
sempre gli 
aggiornamenti in 
cache. 

Non supportato 



Updates? 'ending Non supportato ChangeCount 



UpdateRecordTypes FilterGroup 



StatusFilter 



UpdateStatus RecordStatus UpdateStatus 

OnUpdateError Non supportato OnReconcileError 



ApplyUpdates 
(in dataset o 
database) 

CancelUpdates 



CommitUpdates 



FetchAll 



RevertRecord 



UpdateBatch 



ApplyUpdates 



CancelUpdates o CancelUpdates 
CancelBatch 



Gestito 

automaticamente 



Reconcile 



Non supportato GetNextPacket 

(e PacketRecords) 



CancelBatch 



RevertRecord 



Determina se sono attivi gli 
aggiornamenti in cache. 



Specifica in che modo e isolato il 
dataset rispetto alle modifiche sul 
server. 

Indica se la cache locale contiene 
record aggiornati che devono 
essere applicati al database. 

Indica il tipo di record aggiornati 
da rendere visibile quando si 
applicano gli aggiornamenti in 
cache. 

Indica se un record e invariato, 
modificato, inserito o cancellato. 

Un evento per la gestione degli 
errori di aggiornamento record- 
per-record. 

Applica al database i record nella 
cache locale. 

Rimuove dalla cache locale gli 
aggiornamenti in sospeso senza 
applicarli. 

Cancella la cache di 
aggiornamento dopo che 
l'applicazione degli 
aggiornamenti e andata a buon 
fine. 

Copia i record del database nella 
cache locale per l'editing e 
l'aggiornamento. 

Annulla gli aggiornamenti al 
record corrente nei caso gli 
aggiornamenti non siano ancora 
stati applicati. 
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Applicazioni Internet multipiattaforma 



Un'applicazione Internet e un'applicazione client/ server che utilizza i protocolli 
standard Internet per connettere il client al server. Poiche l'applicazione utilizza i 
protocolli standard Internet per le comunicazioni client /server, e possibile rendere le 
applicazioni indipendenti dalla piattaforma. Ad esempio, un programma lato server 
per un'applicazione Internet comunica con il client tramite il software per Web server 
della macchina. L'applicazione server e di solito scritta per Linux o per Windows, ma 
puo anche essere multipiattaforma. I client possono risiedere su entrambe le 
piattaforme. 

C++Builder consente di creare applicazioni per Web server sotto forma di 
applicazioni CGI o Apache da distribuire in ambiente Linux. In Windows, e possibile 
creare altri tipi di server Web come DLL di Microsoft Server (ISAPI), DLL di 
Netscape Server (NSAPI) o applicazioni CGI Windows. Solo le applicazioni 
prettamente CGI e alcune applicazioni che utilizzano WebBroker potranno essere 
eseguite sia in Windows sia in Linux. 

Porting di applicazioni Internet in Linux 



Se si hanno applicazioni Internet esistenti che si desidera trasformare in applicazioni 
multipiattaforma, e possibile o fare il porting dell'applicazione per Web server in 
Linux o creare una nuova applicazione in Linux quando e disponibile una soluzione 
di C++ di Borland. Per informazioni sulla scrittura di server Web, consultare il 
Capitolo 32, "Creazione di applicazioni server per Internet". Se l'applicazione 
utilizza WebBroker e scrive sull'interfaccia WebBroker e non utilizza chiamate API 
native, non sara molto difficile eseguire il porting in Linux. 

Se l'applicazione scrive su ISAPI, NSAPI, Windows CGI o altre API per Web, sara 
molto piu difficile fare il porting. Sara necessario ricercare queste chiamate API nei 
file sorgente e tradurle in chiamate Apache (consultare ..\Include\Vcl\httpd.hpp 
nella directory Internet per i prototipi delle funzione delle API Apache) o in chiamate 
CGI. E necessario anche apportare tutte le altre modifiche suggerite descritte nel 
paragrafo "Porting di applicazioni Windows in Linux" a pagina 14-2. 
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Capitolo 



15 



Uso di package e di 



componenti 



Un package e una particolare libreria a collegamento dinamico che pud essere usata 
dalle applicazioni C++Builder, dall'IDE o da entrambi. I package di esecuzione 
forniscono funzionalita quando l'utente esegue un'applicazione. I package di 
progettazione vengono usati per installare componenti nell'IDE e per creare speciali 
editor di proprieta per componenti custom. Un singolo package puo funzionare sia 
per la progettazione sia per l'esecuzione e i package di progettazione spesso 
funzionano chiamando i package di esecuzione. Per distinguerle dalle altre DLL, le 
librerie di package vengono memorizzate in file con estensione .bpl (Borland package 
library. 

Come le altre librerie runtime, i package contengono codice che puo essere condiviso 
tra le applicazioni. Ad esempio, i componenti C++Builder usati piu frequentemente 
risiedono in un package chiamato vcl. Ogni volta che si crea una nuova applicazione 
predefinita, essa utilizza automaticamente la vcl. Quando si compila un'applicazione 
creata in questo modo, l'immagine dell'eseguibile dell'applicazione contiene solo il 
codice e i dati che lo caratterizzano; il codice comune si trova nel package di 
esecuzione di nome vcl60.bpl. Un computer sui cui sono state installate diverse 
applicazioni abilitate all'uso del package ha bisogno di una sola copia del file 
vcl60.bpl, che viene condiviso da tutte le applicazioni e anche dall'IDE stesso di 
C++Builder. 

C++Builder viene distribuito con numerosi package di esecuzione precompilati che 
incapsulano i componenti della VCL e della CLX. C++Builder usa i package di 
progettazione anche per trattare i componenti nell'IDE. 

E possibile costruire applicazioni con o senza package. Tuttavia, se si vogliono 
aggiungere componenti personalizzati all'IDE, occorre installarli come package di 
progettazione. 

I package di esecuzione possono essere creati in modo da poterli condividere fra le 
applicazioni. Se si scrivono componenti per C++Builder, e possibile compilarli 
creando dei package di progettazione prima di installarli. 
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Perche usare i package 



I package di progettazione semplificano le operazioni di distribuzione e di 
installazione dei componenti custom. I package di esecuzione, che sono facoltativi, 
offrono diversi vantaggi rispetto alia programmazione convenzionale. Compilando 
del codice riutilizzato in una libreria runtime, e possibile condividerlo tra varie 
applicazioni. Per esempio, tutte le applicazioni — compreso lo stesso C++Builder — 
possono accedere ai componenti standard tramite package. Poiche le applicazioni 
non hanno nei loro eseguibili copie distinte della libreria di componenti, gli eseguibili 
stessi risultano molto piu piccoli, risparmiando risorse di sistema e spazio sul disco 
rigido. Inoltre, i package consentono una compilazione piu rapida, in quanto ad ogni 
compilazione viene compilato solo il codice che caratterizza la specifica applicazione. 

Package e DLL standard 



Quando si vuole ottenere un componente custom che sia disponibile tramite TIDE di 
C++Builder, si deve creare un package. Quando, invece, si desidera costruire una 
libreria che possa essere chiamata da qualsiasi applicazione, indipendentemente 
dallo strumento di sviluppo usato per costruire l'applicazione, si deve creare una 
DLL standard. 

La tabella seguente elenca i tipi di file associati con i package: 

Tabella 15.1 File package 

Estensione del 

file Contenuto 

bpk II file sorgenet delle opzioni di progetto. Questo file e la parte XML del progetto 

del package. ProjectName.bpk e ProjectName.cpp vengono usati in combinazione 
per gestire le impostazioni, le opzioni e i file utilizzati dal progetto del package. 

bpl II package di esecuzione. Questo file e una DLL di Windows con caratteristiche 

specifiche per C++Builder. II nome base del file .bpl e il nome base del file 
sorgente bpk. 

cpp ProjectName.cpp contiene il punto d'ingresso del package. Solitamente, inoltre, 

ogni componente incluso nel package risiede in un file.cpp. 

h II file header o interfaccia per il componente. ComponentName.h e il file 

complementare di ComponentName. cpp. 

lib Una libreria statica, o collection di .obj, usata al posto di un .bpi nel caso in cui 

l'applicazione non usi package di esecuzione. Viene generata solo se e 
selezionata l'opzione -Gl (Generate .LIB File). 

obj Un'immagine binaria di un file unit contenuto in un package. Viene creato, se 

occorre, un file obj per ciascun file .cpp. 

bpi Una libreria di importazione di package Borland (Borland package import 

library). Per ogni package viene creato un singolo file .bpi. I file bpi nel caso 
delle bpl sono analoghi alle librerie di importazione per le dll. Questo file viene 
passato al linker file dalle applicazioni che usano il package per risolvere i 
riferimenti a funzioni presenti nel package. II nome base del bpi e uguale al 
nome base del file sorgente del package. 
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In un package e possibile includere componenti VCL o componenti CLX o entrambi. 
I package destinati all'uso su piu piattaforme dovrebbero includere solo componenti 
CLX. 




In un'applicazione i package condividono i loro dati globali con gli altri moduli. 



Package di esecuzione 



I package di esecuzione vengono distribuiti con le applicazioni C++Builder. Essi 
forniscono funzionalita quando un utente esegue l'applicazione. 

Per eseguire un'applicazione che usa i package, un computer deve contenere sia il file 
.EXE dell'applicazione sia tutti i package (i file .bpl) che essa utilizza. Affinche 
un'applicazione sia in grado di usare i file .bpl, tali file devono essere nel percorso di 
ricerca del sistema. Quando si distribuisce un'applicazione, occorre accertarsi che gli 
utenti abbiano le versioni corrette di tutte i file .bpl necessari. 

Uso dei package in un'applicazione 



Per usare i package in un'applicazione: 

1 Caricare o creare un progetto nell'IDE. 

2 Scegliere Project I Options. 

3 Scegliere il separatore Packages. 

4 Selezionare la casella di controllo "Build with Runtime Packages" e immettere uno 
o piu nomi di package nella casella di testo sottostante. (I package di esecuzione 
associati ai package di progettazione installati sono gia elencati nella casella di 
testo.) 

5 Per aggiungere un package ad un elenco esistente, fare clic sul pulsante Add e 
immettere il nome del nuovo package nella finestra di dialogo Add Runtime 
Package. Per consultare l'elenco di package disponibili, fare clic sul pulsante Add, 
quindi, nella finestra di dialogo Add Runtime Package, fare clic sul pulsante 
Browse accanto alia casella di testo Package Name. 

Se si modifica la casella di testo Search Path della finestra di dialogo Add Runtime 
Package, viene cambiato il Library Path globale di C++Builder. 

Non e necessario includere l'estensione del file nei nomi dei package (ne 
tantomeno il numero che rappresenta la versione di C++Builder); cioe, vcl60.bpl 
viene scritto come vcl. Se si scrive direttamente nella casella di testo Runtime 
Packages, bisogna ricordarsi di separare i nomi con il punto e virgola. Per 
esempio: 

rt 1 ; vcl ; vcldb; vcl ado ; vclx; vclbde ; 

I package elencati nella casella di testo Runtime Packages vengono collegati 
automaticamente all'applicazione. I nomi di package duplicati vengono ignorati, e se 
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la casella di controllo Build with runtime packages e deselezionata, viene eseguito il 
link dell'applicazione senza package. 

I package di esecuzione vengono selezionati solo per il progetto attivo. Per 
trasformare le scelte effettuate in impostazioni predefinite automatiche per i nuovi 
progetti, selezionare la casella di controllo Defaults nella zona inferiore della finestra 
di dialogo. 

Un'applicazione creata con package deve includere anch'essa i file header per le unit 
incluse nel package che essa utilizza. Per esempio, un'applicazione che utilizza i 
controlli per database richiede l'istruzione 

♦include "vcldb.h" 

anche nel caso utilizzi il package vcldb. Nei file sorgenti generati, C++Builder crea 
automaticamente queste istruzioni #include. 

Caricamento dinamico dei package 



Per caricare un package in esecuzione, chiamare la funzione LoadPackage. LoadPackage 
carica il package, controlla eventuali unit duplicate e chiama i blocchi di 
inizializzazione di tutte le unit contenute nel package. Ad esempio, quando si sceglie 
un file in una finestra di dialogo per la selezione di file, potrebbe essere eseguito il 
codice seguente. 

if (OpenDialogl->Execute() ) 

PackageList->ltems->AddObject (OpenDialogl->FileName, (TObject *) LoadPackage (OpenDialogl- 
>FileName) ) ; 

Per scaricare dinamicamente un package, chiamare UnloadPackage. Occorre ricordarsi 
di distruggere qualsiasi istanza delle classi definite nel package e di deregistrare tutte 
quelle classi che sono state registrate dal package. 

Scelta di quali package di esecuzione usare 



C++Builder viene fornito con diversi package di esecuzione, compresi rtl e vcl, che 
forniscono il supporto per il linguaggio di base e per i componenti. 

II package vcl contiene i componenti usati piu di frequente; il package rtl include 
tutte le funzioni di sistema non incluse in componenti e gli elementi dell'interfaccia 
Windows. Non include i componenti database, o altri speciali componenti, che sono 
disponibili in altri package. 

Per creare un'applicazione database client /server che utilizza i package, occorrono 
diversi package di esecuzione, compresi vcl, vcldb,rtl e dbrtl. Se nell'applicazione si 
vogliono usare componenti Outline, occorre anche vclx. Per usare questi package, 
scegliere Project I Options, selezionare il separatore Packages e immettere il seguente 
elenco nella casella di testo Runtime Packages. 

rtl, -vcl, -vcldb; vclx; 

In realta, non e necessario includere vcl ed rtl, in quanto tali package sono 
referenziati nella lista Requires di vcldb. (Vedere l'argomento "Elenco Requires" a 
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pagina 15-10.) L'applicazione sara compilata esattamente alio stesso modo, 
indipendentemente dal fatto che i package vcl e rtl siano inclusi o meno nella casella 
di testo Runtime Packages. 

Package custom 



Un package custom e un file bpl scritto e compilato dall'utente oppure un package 
precompilato fornito da un produttore terzo. Per usare in un'applicazione un 
package custom di esecuzione, scegliere Project I Options ed aggiungere alia casella 
di testo Runtime Packages nella pagina Packages il nome del package. Per esempio, 
si supponga di avere un package di statistica denominato stats.bpl. Per usarlo in 
un'applicazione, la riga da immettere nella casella di testo Runtime Packages sarebbe 
la seguente: 

rt 1, ■ vcl, -vcldb; stats 

Se sono stati creati dei package personalizzati, se necessario e possibile aggiungerli 
all'elenco. 



Package di progettazione 



I package di progettazione vengono usati per installare i componenti nella 
Component palette dell'IDE e per creare speciali editor di proprieta per i componenti 
custom. 

C++Builder viene fornito con i seguenti package di progettazione preinstallati 
nell'IDE. I package installati dipendono dalla versione di C++Builder utilizzata e dal 
fatto che 1'IDE sia stato personalizzato o meno. E possibile vedere una lista dei 
package installati nel sistema scegliendo il comando Component I Install Packages. 

I package di progettazione funzionano chiamando i package di esecuzione che 
vengono referenziati nei rispettivi elenchi Requires. (Vedere l'argomento "Elenco 
Requires" a pagina 15-10.) Per esempio, dclstd contiene riferimenti alia vcl. Lo stesso 
Dclstd contiene un'ulteriore funzionalita che rende disponibile nella Component 
palette la maggior parte dei componenti standard. 

Per convenzione, i package di progettazione dell'IDE design iniziano con del e 
risiedono nella directory bin. Nel caso di package di progettazione, quale ad esempio 
..\bin\ Dclstd, esistono le rispettive controparti per il linker, compresi ..\lib\vcl.lib, 
..\lib\vcl.bpi, e lo stesso package di esecuzione, Windows\System\vcl60.bpl. 

Oltre ai package preinstallati, e possibile installare nell'IDE propri package di 
componenti, o package di componenti di sviluppatori terzi. II package di 
progettazione dclusr viene fornito come contenitore predefinito per nuovi 
componenti. 
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Tutti i componenti vengono installati nell'IDE come package. Nel caso siano stati 
scritti componenti personali, occorre creare e compilare un package che li contenga. 
Vedere "Creazione ed editing dei package" a pagina 15-7.) II codice sorgente del 
componente deve seguire il modello descritto nella Parte V, "Creazione di 
componenti custom". Se si stanno aggiungendo piu unit a un singolo package, e 
ognuna di esse contiene componenti, e necessario creare una singola funzione 
Register per tutti i componenti in un namespace che abbia il nome del package. 

Per installare o disinstallare i propri componenti personali o quelli di produttori 
terzi: 

1 Se si sta installando un nuovo package, copiare o spostare i file package in una 
directory locale. Se il package e stato fornito con i file .bpl, .bpi, .lib e .obj, 
accertarsi di copiarli tutti. (Per informazioni su questi file, vedere "Package e DLL 
standard".) 

La directory in cui vengono memorizzati il file .bpi e i file header, e i file .lib o .obj 
se inclusi nella distribuzione, deve risultare nel Library Path di C++Builder. 

2 Scegliere Component I Install Packages dal menu dell'IDE, oppure scegliere 
Project I Options e fare clic sul separatore Packages. 

3 Sotto "Design packages" appare un elenco dei package disponibili. 

• Per installare un package nell'IDE, selezionare la casella di controllo posta a 
fianco. 

• Per disinstallare un package, deselezionare la relativa casella di controllo. 

• Per vedere l'elenco dei componenti inclusi in un package installato, selezionare 
il package e fare clic su Components. 

• Per aggiungere un package all'elenco, fare clic su Add e ricercare nella finestra 
Add Design Package la directory in cui risiede il file .BPL (vedere il punto 1). 
Selezionare un file .bpl e fare clic su Open. 

• Per rimuovere un package dall'elenco, selezionarlo e fare clic su Remove. 

4 Fare clic su OK. 

I componenti nel package vengono installati nelle pagine della Component palette 
specificate nella procedura RegisterComponents dei componenti, usando i nomi a loro 
assegnati nella stessa procedura. 

I nuovi progetti vengono creati utilizzando tutti i package disponibili installati, a 
meno che non si modifichino le impostazioni predefinite. Per fare si che le opzioni di 
installazione correnti diventino quelle predefinite per tutti i nuovi progetti, 
selezionare la casella di controllo Default nella parte inferiore della pagina Packages 
della finestra di dialogo Project Options. 

Per rimuovere i componenti dalla Component palette senza disinstallare un package, 
selezionare Component I Configure Palette, oppure Tools I Environment Options e 
fare clic sul separatore Palette. II separatore Palette options elenca ciascun 
componente installato insieme al nome della pagina della Component palette in cui 
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esso appare. Selezionando un componente e facendo clic su Hide, il componente 
viene rimosso dalla tavolozza. 

Creazione ed editing dei package 



La creazione di un package richiede che si specifichi: 

• Un nome per il package. 

• Un elenco degli altri package che sono richiesti dal nuovo package, o che sono ad 
esso collegati. 

• Un elenco dei file unit che sono inglobati o collegati al package al momenta della 
compilazione. II package e essenzialmente un wrapper per queste unit di codice 
sorgente. L' elenco Contains indica il luogo in cui vengono collocate le unit di 
codice sorgente per i componenti custom che devono essere compilati in un 
package. 

Un package e definito da un file sorgente C++ (.cpp) e da un file di opzioni di 
progetto il cui nome termina con l'estensione .bpk. Questi file sono generati dal 
Package editor. 

Creazione di un package 



Per creare un package, seguire la procedura riportata di seguito. Per maggiori 
informazioni sui punti qui descritti, consultare "Struttura di un package" a 
pagina 15-9. 

Non utilizzare direttive ifdef in un file package (-bpk) come si fa quando si 
sviluppano applicazioni multipiattaforma. E possibile, tuttavia, utilizzarle nel codice 
sorgente. 

1 Scegliere File I New I Other, selezionare l'icona Package e fare clic su OK. 

2 II package generato viene visualizzato nel Package editor. 

3 II Package editor mostra un nodo Requires e un nodo Contains per il nuovo 
package. 

4 Per aggiungere una unit all'elenco Contains, fare clic sul pulsante Add to package. 
Nella pagina Add unit, scrivere nella casella di testo Unit file name il nome di un 
file .cpp, oppure fare clic su Browse per ricercare il file, quindi fare clic su OK. La 
unit selezionata apparira sotto il nodo Contains nel Package editor. E possibile 
aggiungere altre unit ripetendo la procedura. 

5 Per aggiungere una unit all'elenco Requires, fare clic sul pulsante Add to package. 
Nella pagina Requires, scrivere nella casella di testo Package name il nome di un 
file .bpi, oppure fare clic su Browse per ricercare il file, quindi fare clic su OK. II 
package selezionato appare sotto il nodo Requires nell'editor di Package. E 
possibile aggiungere altri package ripetendo questo operazione. 
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6 Fare clic sul pulsante di scelta rapida Options e decidere il tipo di package che si 
vuol generare. 

• Per creare un package utilizzabile solo in fase di progettazione (un package che 
non puo essere usato in fase di esecuzione), selezionare il pulsante di opzione 
Designtime only. (Oppure aggiungere l'opzione -Gpd del linker al file .bpk: 

LFLAGS = . . . -Gpd . . ..) 

• Per creare un package utilizzabile solo in fase di esecuzione (un package che 
non puo essere installato), selezionare il pulsante di opzione Runtime only. 
(Oppure aggiungere l'opzione -Gpr del linker al file .bpk: LFLAGS = . . . -Gpr . . . .) 

• Per creare un package disponibile in fase di progettazione e di esecuzione, 
selezionare il pulsante di opzione Designtime and runtime. 

7 Per compilare il package, fare clic nel Package editor sul pulsante di scelta rapida 
Compile package. 

P^/jv E possibile anche fare clic sulpulsante Install per forzare l'esecuzione del make. 



Editing di un package esistente 



E possibile aprire un package esistente per apportavi delle modifiche in diversi modi: 

• Scegliere File I Open (o File I Reopen) e selezionare un file cpp o bpk. 

• Scegliere Component I Install Packages, selezionare un package dall'elenco Design 
Packages e fare clic sul pulsante Edit. 

• Non appena l'editor di Package e aperto, selezionare uno dei package nel nodo 
Requires, fare clic-destro e scegliere Open. 

Per modificare la descrizione di un package o impostare le opzioni relative all'uso, 
fare clic nell'editor di Package sul pulsante di scelta rapida Options e selezionare il 
separatore Description. 

La finestra di dialogo Project Options ha una casella di controllo Default nell'angolo 
in basso a sinistra. Se si fa clic su OK quando questa casella e selezionata, le opzioni 
scelte vengono salvate come impostazioni predefinite per nuovi package di progetto. 
Per ripristinare le impostazioni predefinite originali, cancellare o cambiare nome al 
file default.bpk. 



File sorgenti di package e file di opzione di progetto 



I file sorgenti di package hanno estensione .cpp. I file di opzioni di progetto dei 
package vengono creati utilizzando il formato XML ed hanno l'estensione .bpk 
(Borland package). II file di opzione di progetto del package viene visualizzato 
dall'editor dei package facendo clic destro sulla clausola Contains o Requires e 
scegliendo il comando Edit Source Option. 

C++Builder esegue la manutenzione del file .bpk. Solitamente non e necessario 
modificarlo manualmente. Le modifiche dovrebbero essere apportate utilizzando la 
pagina Packages della finestra di dialogo Project Options. 
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II file di opzione di progetto per un package di nome MyPack dovrebbe assomigliare, 
almeno in parte, al seguente: 

<MACR0S> 

<VERSI0N value="BCB.05.02"/> 
<PR0JECT value= "MyPack. bpl"/> 

<0BJFILES value="MyPack.obj Unit2.obj Unit3.obj"/> 
<RESFILES value= "MyPack. res "/> 
<IDLFILES value="'7> 
<IDLGENFILES value= u, 7> 
<DEFFILE value="'7> 

<RESDEPEN value="$(RESFILES) "/> 

<LIBFILES value='"7> 

<LIBRARIES value='"7> 

<SPARELIBS value= ,, Vcl60.1ib'7> 

<PACKAGES value="Vcl60.bpi vcldbx60 .bpi" /> 



In questo caso, MYPACK.cpp dovrebbe includere il codice seguente: 

USERES ("MyPack. res" ) ; 
USEPACKAGE("vcl60.bpi"); 
USEPACKAGE ( "vcldbx60 .bpi " ) ; 
USEUNIT( ,, Unit2.cpp n ) ; 
USEUNIT("Unit3.cpp") ; 

L'elenco Contains di MyPack include tre unit: la stessa MyPack, Unit2 e Unit3. 
L'elenco Requires di MyPack include VCL e VCLDBX. 

Packaging di componenti 

Se si utilizza il New Component wizard per creare componenti (scegliendo il 
comando Component I New Component), ove necessario, C++Builder inserisce la 
macro PACKAGE. Ma se si dispone di componenti custom provenienti da una 
versione precedente di C++Builder, e necessario aggiungere manualmente la macro 
PACKAGE in due punti. 

La dichiarazione del file header per un componente C++Builder deve includere la 
macro predefinita PACKAGE dopo la parola class: 

class PACKAGE MyComponent : ... 

E nel file cpp in cui e definito il componente, includere la macro PACKAGE nella 
dichiarazione della funzione Register: 

void __fastcall PACKAGE Register)) 

La macro PACKAGE viene espansa in un'istruzione che consente di importare ed 
esportare le classi dal file .bpi risultante. 

Struttura di un package 



I package sono composti dalle parti seguenti: 
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• Nome del package 

• Elenco Requires 

• Elenco Contains 

Assegnazione del nome ai package 

All'interno di un progetto, i nomi del package devono essere univoci. Se a un 
package viene assegnato il nome Stats, il Package editor genera un file sorgente e un 
file di opzione di progetto di nome, rispettivamente, Stats. cpp e Stats.bpk; il 
compilatore genera un eseguibile, un'immagine binaria e (facoltativamente) una 
libreria statica di nome Stats.bpl, Stats.bpi e Stats.lib. Per utilizzare il package in 
un'applicazione, aggiungere Stats alia casella di testo Runtime Packages (dopo aver 
scelto il comando Project I Options e aver fatto clic sulla pagina Package). 

Al nome del package e possibile anche aggiungere un prefisso, un suffisso e un 
numero di versione. Mentre il Package editor e aperto, fare clic sul pulsante Options. 
Sulla pagina Description della finestra di dialogo Project Options, imettere del testo o 
un valore per le opzioni LIB Suffix, LIB Prefix, o LIB Version. Ad esempio, per 
aggiungere un numero di versione al progetto del package, immettere 6 dopo LIB 
Version in modo che Packagel generi Packagel. bpl.6. 

Elenco Requires 

L'elenco Requires specifica gli altri package esterni usati dal package attivo. Un 
package esterno incluso nell'elenco Requires viene collegato automaticamente in fase 
di compilazione a qualsiasi applicazione che usi il package attivo e una delle unit 
contenute nel package esterno. 

Se i file unit contenuti nel package fanno riferimento ad altre unit presenti in altri 
package, questi package dovrebbero apparire nell'elenco Requires oppure, nel caso 
non fossero presenti, li si dovrebbe aggiungere. Se gli altri package vengono omessi 
dall'elenco Requires, il compilatore li importera nel package come 'unit contenute 
implicitamente.' 

La maggior parte dei package che vengono creati richiedono rtl. Se si utilizzano 
componenti VCL, sara necessario includere anche il package vcl. Se si utilizzano 
componenti CLX per programmazione multipiattaforma, e necessario includere 
VisualCLX. 

Evitare riferimenti circolari a package 

I package non possono contenere riferimenti circolari nell'elenco Requires. Cio 
significa che 

• Un package non puo fare riferimento a se stesso nel proprio elenco Requires. 

• Una catena di riferimenti deve terminare senza fare riferimento ad alcun package 
della catena. Se il package A richiede il package B, allora il package B non puo 
richiedere il package A; se il package A richiede il package B e il package B 
richiede il package C, allora il package C non puo richiedere il package A. 
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Gestione dei riferimenti duplicati del package 

I riferimenti duplicati nell'elenco Requires del package, o nella casella di testo 
Runtime Packages, vengono ignorati dal compilatore. Per chiarezza di 
programmazione e leggibilita, tuttavia, e opportuno individuare e rimuovere tali 
riferimenti. 

Elenco Contains 

L'elenco Contains identifica i file unit che devono essere inclusi nel package. Se si sta 
scrivendo un package personale, immettere il codice sorgente in file cpp e includerli 
nell'elenco Contains. 

Evitare uses ridondanti nel codice sorgente 

Un package non puo apparire nell'elenco Contains di un altro package. 

Tutte le unit incluse direttamente nell'elenco Contains di un package, o incluse 
indirettamente in una di quelle unit, vengono incorporate nel package in fase di 
collegamento. 

Una unit non puo essere contenuta (direttamente o indirettamente) in piu di un 
package usato dalla stessa applicazione, incluso VIDE di C++Builder. Cio significa che 
se si crea un package che contiene una delle unit in vcl, non sara possibile installare il 
package nell'IDE. Per usare un file unit gia inserito in un altro package, mettere il 
primo package nell'elenco Requires del secondo package. 

Generazione di package 

E possibile compilare un package dall'IDE o dalla riga comandi. Per ricompilare 
automaticamente un package dall'IDE: 

1 Scegliere File I Open, selezionare un file sorgente di package o un file di opzioni di 
progetto e fare clic su Open. 

2 Non appena si apre l'editor, scegliere il comando Project I Make o Project I Build. 

E possibile anche scegliere il comando File I New I Other e fare doppio click su 
Package editor. Fare clic sul pulsante Install per eseguire il make del progetto del 
package. Fare clic destro sui nodi del progetto del package per selezionare le 
opzioni per installare, eseguire il make o il build del package. 

Nel caso si stia aggiungeno un file .cpp non generato in automatico, aggiungere al 
codice sorgente del package una delle direttive del compilatore. Per maggiori 
informazioni, vedere la sezione "Direttive al compilatore specifiche per il 
packaging". 

Quando si esegue il link dalla riga comandi, e possibile utilizzare diverse opzioni del 
linker specifiche per i package. Per maggiori informazioni, consultare "Uso del 
compilatore e del linker dalla riga comandi" a pagina 15-13. 
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Direttive al compilatore specifiche per il packaging 

La tabella seguente elenca le direttive al compilatore specifiche per il packaging che e 
possibile inserire nel codice sorgente. 

Tabella 15.2 Direttive al compilatore specifiche per il packaging 



Fare riferimento al paragrafo "Creazione di package e di DLL" a pagina 7-10 per 
uteriori direttive utilizzabili in tutte le librerie. 

Packaging debole 

La direttiva #pragma package (smart_init, weak) influisce sul modo in cui un file 
.obj viene incorporato nei file .bpi e .bpl del package. (Per informazioni sui file 
generati dal compilatore, vedere il paragrafo "File package creati mediante 
generazione" a pagina 15-13.) Se in un file di unit appare la direttiva #pragma 
package(smart_init, weak), il compilatore, se possibile, omette la unit dalle BPL, e 
crea una copia locale della unit non incorporata nel package nel caso questa venga 
richiesta da un'altra applicazione o da un altro package. Le unit compilate in questo 
modo vengono definite come weakly packaged. 

Si supponga, ad esempio, di aver creato un package chiamato PACK contenente una 
sola unit, UNIT1. Si supponga che UNIT1 non faccia uso di altre unit, ma che faccia 
delle chiamate a RARE.dll. Se quando si compila il package, si inserisce la direttiva 
#pragma package(smart_init, weak) in UNITl.cpp, UNIT1 non verra inclusa in 
PACK. dpi. Non si dovranno distribuire copie di RARE.dll insieme a PACK. Tuttavia, 
UNIT1 continuera a essere inclusa in PACK.bpi. Se UNIT1 viene referenziata da un 
altro package o da un'altra applicazione che utilizzano PACK, questa verra copiata 
da PACK.bpi e compilata direttamente nel progetto. 

Ora, si supponga di aggiungere a PACK una seconda unit, UNIT2. Si supponga 
anche che TJNIT2 utilizzi UNIT1. Questa volta, anche se si compila PACK con la 
direttiva #pragma package(smart_init, weak) in UNITl.cpp, il compilatore includera 
UNIT1 in PACK.bpi. Invece, gli altri package e le altre applicazioni che fanno 
riferimento a UNIT! utilizzeranno la copia (non inserita nel package) presa da 
PACKbpi. 

I file di unit contenenti la direttiva #pragma package(smart_init, weak) non devono 
avere variabili globali. 

La direttiva l#pragma package(smart_init, weak) e una funzionalita avanzata 
destinata agli sviluppatori che distribuiscono le proprie bpl ad altri programmatori 
in C++Builder. Evita la distribuzione di DLL utilizzate raramente ed elimina i 
conflitti tra package che dipendono dalla stessa libreria esterna. 



#pragma package(smart_init, weak) 



#pragma package(smart_init) 



Direttiva 




15-12 Guida alia programmazione 



Creazione ed editing dei package 



Ad esempio, la unit Pen Win di C++Builder fa riferimento a PenWin.dll. Pochi 
progetti utilizzano Pen Win e nella maggior parte degli elaboratori PenWin.dll non e 
installata. Per questo motivo, la unit Pen Win e incorporata "debolmente"nella vcl. 
Quando si compila un progetto che utilizza PenWin e il package vcl, PenWin viene 
copiata da vcl60.bpi e incorporata direttamente nel progetto; il file eseguibile 
risultante e collegato in modo statico a PenWin.dll. 

Se PenWin non fosse incorporata debolmente, sorgerebbero due problemi. Primo, la 
stessa vcl sarebbe collegata in modo statico a PenWin.dll, per cui non la si potrebbe 
caricare in quei computer in cui PenWin.dll non e installata. Secondo, se si tentasse di 
creare un package contenente PenWin, si otterrebbe un errore del compilatore perche 
la unit PenWin sarebbe contenuta sia in vcl che nel package. Di conseguenza, in 
assenza di un packaging debole, non si potrebbe includere PenWin nelle 
distribuzioni standard della vcl. 

Uso del compilatore e del linker dalla riga comandi 

Quando si compila dalla riga comandi, utilizzare l'opzione -Tpp del linker per 
assicurarsi che il progetto venga generato come package. Altre opzioni specifiche per 
i package sono elencate nella tabella seguente. 

Tabella 15.3 Opzioni del linker della riga comandi specifiche per i package 



Opzione Scopo 

-Tpp Genera il progetto come package. Inclusa per impostazione predefinita nei file 

di progetto dei package. 

-Gi Salva il file bpi generato. Inclusa per impostazione predefinita nei file di 

progetto dei package. 

-Gpr Genera un package da usare solo in esecuzione. 

-God Genera un package da usare solo in progettazione. 

-Gl Genera un file .lib. 

-D "description" Salva la descrizione specificata con il package. 



Le opzioni -Gpr e -Gpd corrispondono alle caselle di controllo Runtime Package e 
Design Package presenti sulla pagina Description della finestra di dialogo Project 
Options (disponibile solo per i progetti di package); se non si utilizza ne -Gpr ne - 
Gpd, il package risultante funziona sia in progettazione sia in esecuzione. L'opzione 
-D corrisponde alia casella di testo Description sulla stessa pagina. L'opzione -Gl 
corrisponde alia casella di controllo Generate .lib File presente sulla pagina Linker 
della finestra di dialogo Project Options. 

E possibile generare un file make da utilizzare dalla riga comandi scegliendo il 
comando Project I Export Makefile. 

File package creati mediante generazione 

Per creare un package, si compila un file sorgente (.cpp) che utilizza un file di opzioni 
di progetto con estensione .bpk. II nome base del file sorgente dovrebbe coincidere 
col nome base dei file generato dal compilatore; ovvero, se il file sorgente si chiama 
TRAYPAK.cpp, il file di opzioni di progetto — TRAYPAK.bpk — dovrebbe includere 
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<PR0JECT value="Traypak.bpl"/> 

In questo caso, compilando il progetto verra creato un package di nome 
TRAYPAK.bpl. 

Quando si esegue la compilazione e il link di un package, si crea un file bpi, un bpl, 
un obj, e un lib. Quando li si compila, per impostazione predefinita i file bpi, bpl e di 
libreria vengono generati nelle directory specificate nella pagina Library della 
finestra di dialogo Tools I Environment Options. E possibile ridefinire le impostazioni 
predefinite facendo clic sul pulsante di scelta rapida Options nell'editor di package in 
modo da visualizzare la finestra di dialogo Project Options; apportare le necessarie 
modifiche sulla pagina Directories /Conditionals. 

Distribuzione dei package 



I package vengono distribuiti in modo analogo ad altre applicazioni. I file che 
vengono distribuiti con un package distribuito possono essere svariati. E necessario 
distribuire il file bpl e tutti i package o le dll richieste dalla bpl. 

La tabella seguente elenca i file che potrebbe essere necesarrio distribuire a seconda 
dell'uso che si intende fare del package. 



Tabella 15.4 File distribuiti con un package 


File 


Descrizione 


Componen tName.h 
Componen tName. cpp 
bpi, obj, and lib 


Consente agli utente di accedere alle interfacce della classe. 
Consente agli utente di accedere al sorgente dell componente. 
Consente agli utente di eseguire il link dellle applicazioni. 



Per informazioni generali sulla distribuzione, fare riferimento al Capitolo 17, 
"Distribuzione di applicazioni". 



Distribuzione di applicazioni che usano package 



Quando si distribuisce un'applicazione che usa package di esecuzione, occorre 
accertarsi che gli utenti abbiano sia il file .exe dell'applicazione sia tutti i file di 
libreria (.bpl o .dll) chiamati dall'applicazione. Se i file di libreria si trovano in una 
directory diversa da quella del file .exe, devono essere accessibili tramite il percorso 
dell'utente. E opportuno seguire la convenzione di mettere i file di libreria nella 
directory Windows \ System. Se si usa InstallShield Express, lo script di installazione 
puo controllare il sistema dell'utente per rilevare quali package sono necessari, prima 
di reinstallarli alia cieca. 

Distribuzione di package ad altri sviluppatori 



Se si distribuiscono package di esecuzione o di progettazione ad altri sviluppatori 
C++Builder, assicurarsi di fornire entrambi i file .bpi e .bpl oltre a tutti gli altri file 
header necessari. Affinche gli sviluppatori possano collegare staticamente i 
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componenti nelle proprie applicazioni, vale a dire generare applicazioni che non 
utilizzano package di esecuzione, sara necessario distribute anche i file .lib (o .obj) 
per tutti i package forniti. 

File di raccolta di package 



Le raccolte di package (file .dpc) rappresentano un modo pratico per distribute 
package ad altri sviluppatori. Ogni raccolta di package contiene uno o piu package, 
inclusi i file bpl e tutti i file aggiuntivi che si desidera distribuire. Quando si seleziona 
una raccolta di package per installarla nell'IDE, i file costituenti vengono estratti 
automaticamente dal rispettivo contenitore .pee; la finestra di dialogo Installation 
offre la possibility di installare tutti i package inclusi nella raccolta oppure di 
installarli in modo selettivo. 

Per creare una raccolta del package: 

1 Scegliere Tools I Package Collection Editor in modo da aprire l'editor Package 
Collection. 

2 Fare clic sul pulsante di scelta rapida Add a Package, quindi selezionare una bpl 
nella finestra di dialogo Select Package e fare clic su Open. Per aggiungere altre 
bpl alia raccolta, fare di nuovo clic sul pulsante di scelta rapida Add a Package. 
Alia sinistra del Package editor appare un diagramma ad albero che visualizza le 
bpl man mano che vengono aggiunte. Per rimuovere un package, selezionarlo e 
fare clic sul pulsante di scelta rapida Remove Package. 

3 Selezionare il nodo Collection in cima al diagramma ad albero. Sul lato destro 
dell'editor Package Collection appariranno due campi: 

• Nella casella di testo Author/Vendor Name, e possibile immettere una serie di 
informazioni facoltative sulla raccolta di package che appariranno nella finestra 
di dialogo Installation, nel momento in cui gli utenti installeranno i package. 

• Nella casella Directory List, elencare le directory predefinite in cui si vuole che 
vengano installati i file inclusi nella raccolta di package. Utilizzare i pulsanti 
Add, Edit e Delete per modificare questo elenco. Per esempio, si supponga che 
si desideri che tutti i file di codice sorgente vengano copiati nella stessa 
directory. In questo caso, si dovrebbe immettere il nome Source nella casella 
Directory Name e C : \MyPackage\Source nel campo Suggested Path. La finestra di 
dialogo di Installation visualizzera C : \MyPackage\Source come percorso suggerito 
per la directory. 

4 Oltre alle bpl, la raccolta di package puo contenere file .bpi, .obj e .cpp (i file unit), 
file di documentazione e tutti gli altri file che si desidera includere nella 
distribuzione. I file subordinati vengono collocati in gruppi di file associati con gli 
specif ici package (bpl); i file in un gruppo vengono installati solo quando viene 
installata la bpl associata. Per collocare i file subordinati nella raccolta di package, 
selezionare una bpl nel diagramma ad albero e fare clic sul pulsante di scelta 
rapida Add File Group; scrivere un nome per il gruppo di file. Se si vuole, 
aggiungere altri file di gruppo nello stesso modo. Quando si seleziona un gruppo 
di file, sulla destra del Package Collection editor appariranno dei nuovi campi. 
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• Dalla casella di riepilogo Install Directory, selezionare la directory in cui si 
vuole che vengano installati i file del gruppo selezionato. L'elenco a discesa 
include le directory immesse in Directory List al punto 3 visto in precedenza. 

• Selezionare la casella di controllo Optional Group se si vuole che l'installazione 
dei file nel gruppo selezionato sia facoltativa. 

• Nella casella Include Files, elencare i file che si desidera includere nel gruppo 
selezionato. Utilizzare i pulsanti Add, Delete e Auto per modificare l'elenco. II 
pulsante Auto consente di selezionare tutti i file con le estensioni specificate 
elencati nell'elenco Contains del package; il Package Collection editor utilizza il 
percorso globale Library Path di C++Builder per cercare questi file. 

5 YE possibile selezionare le directory di installazione per i package elencati 
nell'elenco Requires di qualsiasi package incluso nella raccolta. Quando si 
seleziona una bpl nel diagramma ad albero, sul lato destro del Package Collection 
editor appaiono quattro nuovi campi: 

• Nella casella di riepilogo Required Executables, selezionare la directory in cui si 
desidera vengano installati i file .bpl dei package elencati nell'elenco Requires. 
(L'elenco a discesa include le directory immesse in Directory List al punto 3 
visto in precedenza). II Package Collection editor cerca questi file utilizzando il 
percorso globale Library Path di C++Builder e li elenca in Required Executable 
Files. 

• Nella casella di riepilogo Required Libraries, selezionare la directory in cui si 
desidera vengano installati i file obj e .bpi dei package inclusi nell'elenco 
Requires. (L'elenco a discesa include le directory immesse in Directory List al 
punto 3 visto in precedenza). II Package Collection editor cerca questi file 
utilizzando il percorso globale Library Path di C++Builder e li elenca in 
Required Library Files. 

6 Per salvare il file sorgente della raccolta di package, scegliere File I Save. I file 
sorgenti di una raccolta di package dovrebbero essere salvati con l'estensione .pee. 

7 Per generare la raccolta di package, fare clic sul pulsante di scelta rapida Compile. 
II Package Collection editor genera un file .dpc avente lo stesso nome del file 
sorgente (.pee). Se il file sorgente non e ancora stato salvato, prima di compilare 
l'editor chiede di assegnare un nome al file. 

Per modificare o ricompilare un file .pee esistente, selezionare nel Package Collection 
editor il comando File I Open e individuare il file su cui si vuole operare. 
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Capitolo 




Creazione di applicazioni 

intemazionali 

In questo capitolo vengono descritte le linee guida per la scrittura di applicazioni che 
si intende immettere sul mercato internazionale. Pianificando per tempo l'obiettivo, e 
possibile ridurre la quantita di tempo e di codice necessari per rendere l'applicazione 
valida anche sui mercati esteri e non solo su quello interno. 

Internazionalizzazione e localizzazione 



Per creare un'applicazione che possa essere distribuita nei mercati esteri, devono 
essere effettuate due operazioni fondamentali: 

• L'internazionalizzazione 

• La localizzazione 

Se la versione acquistata di C++Bulider include il modulo Translation Tools, e 
possibile utilizzarlo per gestire la localizzazione. Per maggiori informazioni, 
consultare la Guida in linea relativa a Translation Tools (ETM.hlp). 

Internazionalizzazione 



L'internazionalizzazione e il processo che permette al programma di funzionare in 
localita diverse. Una localita e costituita dall'ambiente utente, che comprende le 
convenzioni culturali del paese di destinazione e la lingua. Windows supporta un 
ampio numero di localita, ciascuna delle quali viene descritta tramite una lingua e 
una nazione. 
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Localizzazione 



La localizzazione e la procedura di traduzione di un'applicazione in modo che sia in 
funzione in una determinata localita. Oltre alia traduzione delle stringhe che 
appaiono nell'interfaccia utente, la localizzazione comprende l'adattamento delle 
funzionalita alle caratteristiche specifiche della nazione. Per esempio, 
un'applicazione finanziaria puo essere modificata in modo da tener conto delle 
differenti forme di tassazione previste nei diversi stati. 

Internazionalizzazione delle applicazioni 



Per creare applicazioni internazionalizzate, e necessario attenersi alle seguenti regole 
generali: 

• Abilitare il proprio codice alia gestione di stringhe con set di caratteri 
internazionali. 

• Progettare l'interfaccia utente in modo che possa accettare le modifiche derivanti 
dalla localizzazione. 

• Isolare tutte le risorse che necessitano di una localizzazione. 

Abilitazione del codice dell'applicazione 

E necessario accertarsi che il codice dell'applicazione sia in grado di gestire le 
stringhe che incontrera nelle varie localita di destinazione. 

Set di caratteri 

Le edizioni occidentali di Windows (quella inglese, francese e tedesca incluse) 
utilizzano il set di caratteri ANSI Latin-1 (1252). Altre edizioni di Windows usano, 
invece, set differenti di caratteri. Per esempio, la versione giapponese di Windows 
utilizza il set di caratteri Shift-JIS (code page 932), che rappresenta i caratteri 
giapponesi come codici di caratteri multibyte. 

In generale esistono tre tipi di set di caratteri: 

• Singolo byte 

• Multibyte 

• Caratteri estesi 

Windows e Linux supportano entrambi set di caratteri a singolo byte e multibyte 
oltre a Unicode. In un set di caratteri a singolo byte, ogni byte in una stringa 
rappresenta un carattere. II set di caratteri ANSI utilizzato da molti sistemi operativi 
occidentali e un set di caratteri a singolo byte. 

In un set di caratteri multibyte, alcuni caratteri sono rappresentati da un byte e altri 
da piu di un byte. II primo byte di un carattere multibyte e chiamato il byte iniziale. 
Di solito, i primi 128 caratteri di un set di caratteri multibyte corrispondono ai 
caratteri ASCII a 7 bit e tutti i byte il cui valore ordinale e maggiore di 127 e il byte 
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iniziale di un carattere multibyte. Solo i caratteri a singolo byte possono contenere il 
valore null (#0). I set di caratteri multibyte - in particolare i set di caratteri a doppio 
byte (DBCS) - sono ampiamente utilizzati per le lingue asiatiche. 

Set di caratteri OEM e ANSI 

A volte e necessario effettuare la conversione tra il set di caratteri di Windows (ANSI) 
e il set di caratteri specificato dalla code page della macchina utente (denominato set 
di caratteri OEM). 

Set di caratteri multibyte 

I caratteri ideografici utilizzati in Estremo Oriente non possono usare la semplice 
mappatura 1:1 tra i caratteri del linguaggio e il tipo char a un byte (8 bit). Queste 
lingue possiedono troppi caratteri per poter essere rappresentati usando il tipo char a 

I byte. Invece, una stringa multibyte puo contenere uno o piu byte per carattere. 
AnsiStrings puo contenere una miscela di caratteri a singolo byte e caratteri 
multibyte. 

II primo byte di ogni codice di carattere multibyte deriva da un intervallo riservato 
che dipende dal particolare set di caratteri. II secondo e i successivi byte possono 
essere talvolta gli stessi del codice di carattere per un carattere distinto a 1 byte, 
oppure possono essere compresi nell'intervallo riservato al primo byte dei caratteri 
multibyte. Pertanto, l'unico modo per distinguere se un determinate byte di una 
stringa rappresenta un singolo carattere o una parte di un carattere multibyte 
consiste nel leggere la stringa, partendo dall'inizio, analizzandola in caratteri a due o 
piu byte non appena si incontra un byte iniziale proveniente dall'intervallo riservato. 

Quando si scrive un programma per paesi asiatici, bisogna ricordarsi di gestire tutte 
le operazioni sulle stringhe con funzioni in grado di analizzare le stringhe come 
caratteri multibyte. Per un elenco delle funzioni RTL che possono operare con 
caratteri multibyte, consultare le sezioni "International API" e "MCBS utilites" della 
Guida in linea. 

Occorre tenere presente che la lunghezza delle stringhe in byte non corrisponde 
necessariamente alia lunghezza delle stringhe in caratteri. Si deve fare attenzione a 
non troncare le stringhe tagliando a meta un carattere multibyte. Non si devono, 
inoltre, passare caratteri come parametri a funzioni o procedure, poiche le 
dimensioni di un carattere non possono essere conosciute in prima istanza. Invece, e 
sempre necessario passare un puntatore a un carattere o a una stringa. 

Caratteri estesi 

Un altro approccio per lavorare con i set di caratteri ideografici e quello di convertire 
tutti i caratteri in uno schema di codifica del carattere esteso come Unicode. I caratteri 
e le stringhe Unicode sono anche chiamati wide characters e wide character string. 
Nel set di caratteri Unicode, ogni carattere e rappresentato da due byte. Pertanto una 
stringa Unicode e una sequenza non di singoli byte ma di word composte da due 
byte. 

I primi 256 caratteri Unicode mappano il set di caratteri ANSI. II sistema operativo 
Windows supporta Unicode (UCS-2). II sistema operativo Linux supporta UCS-4, un 
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superset di UCS-2. C++Builder supporta UCS-2 su entrambe le piattaforme. Poiche i 
wide character sono lunghi due byte anziche uno, il set di caratteri puo rappresentare 
un numero maggiore di caratteri differenti. 

Usando uno schema di codifica dei caratteri esteso, si ha il vantaggio di poter 
effettuare molte delle solite assunzioni sulle stringhe che non funzionano per i 
sistemi MBCS. C'e una relazione diretta tra il numero di byte e il numero di caratteri 
di una stringa. Non occorre preoccuparsi di tagliare i caratteri a meta ne di 
confondere la seconda meta di un carattere con l'inizio di un altro carattere. 

II maggiore inconveniente quando si lavora con i caratteri estesi sta nel fatto che 
Windows supporta solo poche chiamate alle funzioni API dei caratteri estesi. Per 
questo motivo, i componenti VCL rappresentano tutti i valori delle stringhe come 
stringhe a un solo byte o MBCS. La traduzione dal sistema wide character al sistema 
MBCS tutte le volte che si imposta una proprieta stringa o se ne legge il valore 
richiede del codice aggiuntivo che rallenta l'applicazione. $Tuttavia, puo essere 
opportuna la traduzione in caratteri estesi per alcuni algoritmi di elaborazione di 
particolari stringhe che hanno bisogno di sfruttare i vantaggi del mappatura 1:1 tra 
caratteri e WideChars. 

Per un elenco delle funzioni RTL che possono operare con caratteri Unicode, 
consultare la sezione "International API" nella Guida in linea. 

Inclusione di funzionalita bidirezionali nelle applicazioni 

Alcune lingue non seguono la lettura da sinistra a destra utilizzata solitamente nei 
paesi occidentali, ma leggono le parole da destra a sinistra e i numeri da sinistra a 
destra. Tali lingue vengono definite bidirezionali (BiDi) proprio per questa 
particolarita di comportamento. Le lingue bidirezionali piu diffuse sono l'Arabo e 
l'Ebraico, ma anche altre lingue del Medio-Oriente sono bidirezionali. 

TApplication ha due proprieta, BiDiKeyboard e NonBiDiKeyboard, che consentono di 
specificare il layout di tastiera. Oltre a cio, la VCL supporta la localizzazione 
bidirezionale mediante le proprieta BiDiMode e ParentBiDiMode. La tabella seguente 
elenca gli oggetti VCL che hanno queste proprieta: 

Tabella 16.1 Oggetti VCL che supportano BiDi 



Pagina della C 



lette OggettoVCL 



Standard 



TButton 



TCheckBox 



TComboBox 



TEdit 



TGroupBox 
TLabel 



TListBox 



TMainMenu 



TMemo 



TPanel 



TPopupMenu 
TRadioButton 
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Tabella 16.1 Oggetti VCL che supportano BiDi (continua) 
Pagina della Component palette Oggetto VCL 

TRadioGroup 
TScrollBar 



Additional 



TActionMainMenuBar 

TActionToolBar 

TBitBtn 

TCheckListBox 

TColorBox 

TDrawGrid 

TLabeledEdit 

TMaskEdit 

TScrollBox 

TSpeedButton 

TStaticLabel 

TStaticText 

TStringGrid 

TValueListEditor 



Win32 



TComboBoxEx 

TDateTimePicker 

THeaderControl 

THotKey 

TListView 

TMonthCalendar 

TPageControl 

TRichEdit 

TStatusBar 

TTabControl 

TTreeView 



Data Controls 



TDBCheckBox 

TDBComboBox 

TDBEdit 

TDBGrid 

TDBListBox 

TDBLookupComboBox 

TDBLookupListBox 

TDBMemo 

TDBRadioGroup 

TDBRichEdit 

TDBText 



QReport 



TQRDBText 

TQRExpr 

TQRLabel 
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Tabella 16.1 Oggetti VCL che supportano BiDi (continua) 
Pagina della Component palette Oggetto VCL 

TQRMemo 

TQRPreview 

TQRSysData 

Altre classi TApplication (non ha ParentBiDiMode) 

TBoundLabel 

TControl (non ha ParentBiDiMode) 
TCustomHeaderControl (non ha ParentBiDiMode) 
TForm 
TFrame 

THeaderSection 

THintWindow (non ha ParentBiDiMode) 

TMenu 

TStatusPanel 

THintWindow sceglie il BiDiMode del controllo che ha attivato il suggerimento. 

Proprieta bidirezionali 

Gli oggetti elencati nella Tabella 16.1, "Oggetti VCL che supportano BiDi," a pagina 
16-4 hanno le proprieta BiDiMode e ParentBiDiMode. Queste proprieta, come 
BiDiKeyboard di TApplication e NonBiDiKeyboard, supportano la localizzazione 
bidirezionale. 

Le proprieta bidirezionali non sono disponibili nella programmazione 
multip iattaf or ma . 

Proprieta BiDiMode 

La proprieta BiDiMode e un nuovo tipo enumerato, TBiDiMode, con quattro stati: 
bdLeftToRight, bdRightToLeft, bdRightToLeftNoAlign e bdRightToLeftReadingOnly. 

bdLeftToRight 

bdLeftToRight traccia il testo per la lettura da sinistra a destra. L'allineamento e le 
barre di scorrimento non vengono modificate. Per esempio, quando si immette del 
testo da destra a sinistra, come nella lingua araba o ebraica, il cursore entra in 
modalita "spinta" e il testo viene introdotto da destra a sinistra. II testo nelle lingue 
neolatine, come l'lnglese o il Francese, viene immesso da sinistra a destra. 
bdLeftToRight e il valore predefinito. 

Figura 1 6.1 TListBox impostato a bdLeftToRight 



123abo 
123 .il 
123 abc 



1 
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bdRightToLeft 

bdRightToLeft traccia il testo per la lettura da destra a sinistra, l'allineamento viene 
modificato e la barra di scorrimento viene spostata. II testo viene immesso nel solito 
modo per lingue come l'arabo o l'ebraico, che richiedono l'immissione da destra a 
sinistra. Quando si imposta la tastiera per le lingue neolatine, il cursore entra in 
modalita "spinta" e il testo viene introdotto da sinistra a destra. 

Figura 16.2 TListBox impostato a bdRightToLeft 





abc ITT 




abc ITT 


abc ITT 



bdRightToLeftNoAlign 

bdRightToLeftNoAlign traccia il testo per la lettura da destra a sinistra, non modifica 
rallineamento e non sposta le barre di scorrimento. 

Figura 1 6.3 TListBox impostato a bdRightToLeftNoAlign 



abc ITT 
abc ITT 
abc 1TT 



bdRightToLeftReadingOnly 

bdRightToLeftReadingOnly riporta il testo da destra a sinistra e non modifica ne 
rallineamento ne le barre di scorrimento. 

Figura 16.4 TListBox impostato a bdRightToLeftReadingOnly 

__ 

abc ITT 
abc 1TT 



1 



Proprieta ParentBiDiMode 

ParentBiDiMode e una proprieta booleana. Quando e impostato a true (impostazione 
predefinita), il controllo cerca il proprio genitore per stabilire quale BiDiMode usare. 
Se il controllo e un oggetto TForm, la scheda usa l'impostazione di BiDiMode di 
Application. Se tutte le proprieta ParentBiDiMode sono impostate a true, quando si 
cambia la proprieta BiDiMode di Application, tutte le schede e i controlli del progetto 
vengono aggiornati con la nuova impostazione. 

Metodo FlipChildren 

II metodo FlipChildren consente di invertire la posizione di un figlio del controllo 
contenitore. I controlli contenitori sono controlli che accettano altri controlli, come 
TForm, TPanel e TGroupBox. FlipChildren ha un unico parametro booleano, AllLevels. 
Quando e impostato a false, solo i figli diretti del controllo contenitore vengono 
invertiti. Quando e impostato a true, vengono invertiti tutti i livelli dei figli del 
controllo contenitore. 

C++Builder inverte i controlli cambiando la proprieta Left e il loro allineamento. Se la 
parte sinistra di un controllo di testo e a cinque pixel dal margine sinistro del suo 
controllo genitore, una volta invertito la parte destra del controllo di testo e a cinque 
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pixel dal margine destro del controllo genitore. Se il controllo di testo e allineato a 
sinistra, la chiamata di FlipChildren fara si che lo stesso venga allineato a destra. 

Per invertire un controllo in fase di progettazione, occorre selezionare Edit I Flip 
Children, quindi All o Selected, a seconda del fatto che si intendano invertire tutti i 
controlli o solo i figli del controllo selezionato. E anche possibile invertire un 
controllo selezionandolo sulla scheda, facendo clic con il pulsante destro e 
selezionando Flip Children dal menu contestuale. 

La selezione di un controllo di testo e l'esecuzione di un comando Flip Children I 
Selected non produce alcun effetto. Cio e dovuto al fatto che i controlli di testo non 
sono contenitori. 



Ulteriori metodi 

Ci sono diversi altri metodi che possono essere utilizzati per lo sviluppo di 
applicazioni per utenti di lingue bidirezionali. 

Tabella 16.2 Metodi della VCL che supportano BiDi 
Metodo Descrizione 



OkToChangeFieldAlignment 
DBUseRightToLeftAlignment 
ChangeBiDiModeAlignment 



IsRightToLeft 

UseRightToLeftReading 
UseRightToLeftAlignment 

UseRightToLeftScrollBar 
DrawTextBiDiModeFlags 
DrawTextBiDiModeFlagsReadingOnly 

AddBiDiModeExStyle 



Usato con i controlli database. Verifica se l'allineamento 
di un controllo pud essere modificato. 

Un wrapper per controlli database destinato alia verifica 
dell'allineamento. 

Cambia il parametro di allineamento che gli viene 
passato. Non effettua alcuna verifica dell'impostazione 
di BiDiMode, ma si limita a convertire l'allineamento a 
sinistra nell'allineamento a destra e viceversa, senza 
modificare i controlli allineati al centra. 

Restituisce true se e selezionata una delle opzioni da 
destra a sinistra. Se restituisce false, il controllo e in 
modalita da sinistra a destra. 

Restituisce true se il controllo usa la lettura da destra a 
sinistra. 

Restituisce true se il controllo usa la lettura da destra a 
sinistra. Puo essere ridefinito nel caso occorra 
personalizzarlo. 

Restituisce true se il controllo usa una barra di 
scorrimento a sinistra. 

Restituisce i flag per tracciare correttamente il testo per 
il BiDiMode del controllo. 

Restituisce i flag per tracciare correttamente il testo per 
il BiDiMode del controllo, limitando il flag alia sua 
modalita di lettura. 

Aggiunge i flag ExStyle appropriati al controllo da 



Funzioni specifiche della localita 

E possibile aggiungere alle applicazioni altre funzioni relative a una determinata 
localita. In particolare, per gli ambienti di lingue asiatiche, puo essere necessario che 
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l'applicazione controlli l'editor del metodo di input (IME) che viene usato per 
convertire la sequenza di tasti premuti dall'utente in stringhe di caratteri. 

I componenti della VCL e della CLX offrono il supporto per la programmazione 
dell'IME. La maggior parte dei controlli con finestra che operano direttamente con 
l'immissione del testo ha una proprieta ImeName che consente di specificare il 
particolare IME che verra usato quando il controllo riceve il fuoco di immissione. Essi 
forniscono anche una proprieta ImeMode che specifica come TIME convertira l'input 
da tastiera. TWinControl introduce diversi metodi protetti che sono in grado di 
controllare 1'IME dalle classi che vengono definite. Inoltre, la variabile globale Screen 
fornisce informazioni sugli IME disponibili nel sistema dell'utente. 

La variabile globale Screen (disponibile nella VCL e nella CLX) fornisce anche 
informazioni sulla mappa di tastiera installata sul sistema dell'utente. E possibile 
usare questa variabile per ottenere informazioni specifiche della localita 
suU'ambiente in cui viene eseguita l'applicazione. 



Progettazione di un'interfaccia utente 



Quando si crea un'applicazione per diversi mercati esteri, e importante progettare 
l'interfaccia utente in modo tale che possa adattarsi alle modifiche necessarie in fase 
di traduzione. 



Testo 

Tutto il testo che appare nell'interfaccia utente deve essere tradotto. II testo in Inglese 
e quasi sempre piu breve di quello tradotto. Gli elementi dell'interfaccia utente 
devono essere progettati in modo da poter accogliere anche testi piu lunghi. Le 
finestre di dialogo, i menu, le barre di stato e gli altri elementi dell'interfaccia utente 
che mostrano del testo devono essere creati in modo da poter visualizzare con facilita 
stringhe piu lunghe. Occorre evitare le abbreviazioni — che non esistono nelle lingue 
che utilizzano caratteri ideografici. 

Le stringhe brevi tendono a crescere in fase di traduzione piu delle frasi lunghe. La 
Tabella 16.3 fornisce una stima approssimativa dell'espansione prevista della 
lunghezza di una stringa in Inglese: 

Tabella 16.3 Lunghezza stimata delle stringhe 
Lunghezza della stringa in Inglese (in caratteri) Incremento stimato 

1-5 100% 

6-12 80% 

13-20 60% 

21-30 40% 

31-50 20% 

over 50 10% 
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Immagini 

Teoricamente si possono usare immagini che non richiedono traduzione. 
Owiamente, cio presuppone che esse non contengano testo, il quale richiede sempre 
una traduzione. Se si deve inserire del testo nelle immagini, e consigliabile utilizzare 
un oggetto etichetta con uno sfondo trasparente e collocarlo su un'immagine anziche 
includere il testo come parte dell'immagine. 

Ci sono altre considerazioni da fare quando si creano immagini. Bisogna evitare, se 
possibile, di usare immagini specifiche di una particolare cultura. Per esempio, le 
caselle di posta assumono un aspetto diverso a seconda dei paesi. I simboli religiosi 
devono essere evitati se l'applicazione e destinata a paesi che hanno religioni 
predominanti diverse. Anche i colori possono avere connotazioni simboliche 
differenti in culture diverse. 

Formati e ordinamento 

II formato della data, dell'ora, dei numeri e della valuta nell'applicazione deve essere 
quello del paese a cui l'applicazione e destinata. Se si utilizzano formati specifici di 
Windows, non occorre modificarli, in quanto la relativa trasformazione viene 
effettuata dal registro di Windows dell'utente. Se, invece, si specificano delle stringhe 
di formato proprie, bisogna ricordarsi di dichiararle come costanti di risorsa in modo 
che possano essere localizzate. 

Anche l'ordine in cui le stringhe vengono ordinate varia da paese a paese. Molte 
lingue europee includono dei segni diacritici che sono ordinati in modo diverso a 
seconda del paese. Inoltre, in alcun paesi, le combinazioni di due caratteri sono 
considerate un singolo carattere in fase di ordinamento. Per esempio, in spagnolo la 
combinazione ch viene ordinata come un'unica lettera intermedia tra la c e la d. A 
volte un singolo carattere viene ordinato come se fosse costituito da due caratteri 
separati, come il tedesco eszett. 

Configurazione della tastiera 

Occorre prestare attenzione nell'assegnazione di comandi di scelta rapida ad alcune 
combinazioni di tasti. Non tutti i caratteri disponibili nelle tastiere americane sono 
facilmente riproducibili nelle tastiere internazionali. Quando e possibile, per i tasti di 
scelta rapida e consigliabile utilizzare i tasti numerici e i tasti funzione, in quanto 
sono disponibili su tutte le tastiere. 

Isolamento delle risorse 



L'operazione piu ovvia nella localizzazione di un'applicazione e la traduzione delle 
stringhe che appaiono nell'interfaccia utente. Per creare un'applicazione che possa 
essere tradotta senza dover modificare il codice, bisogna isolare le stringhe 
dell'interfaccia utente in un unico modulo. C++Builder crea automaticamente un file 
.dfm ( .xfm nelle applicazioni CLX) che contiene le risorse per i menu, le finestre di 
dialogo e le bitmap. 
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Oltre a questi elementi owi dell'interfaccia utente, occorre isolare anche tutte le 
stringhe, come i messaggi di errore, che vengono presentate all'utente. Le risorse 
stringa non vengono incluse nel file scheda, ma e possibile isolarle in un file .RC. 

Creazione di DLL di risorse 



L'isolamento delle risorse semplifica il processo di traduzione. II livello successivo di 
separazione delle risorse e la creazione di DLL di risorse. Una DLL di risorse contiene 
solo le risorse per un programma. Le DLL di risorse consentono di creare programmi 
che supportano traduzioni diverse semplicemente cambiando la DLL di risorsa 
utilizzata. 

Per creare DLL di risorse per i propri programmi, si deve ricorrere al Resource DLL 
wizard. II Resource DLL wizard richiede un progetto aperto, salvato e compilato. 
Verra creato un file RC contenente le tabelle delle stringhe usate dai file RC e le 
stringhe resourcestring del progetto, e verra generato un progetto per una risorsa di 
tipo DLL contenente le schede rilevanti e il file RES creato. Quest'ultimo verra 
compilato dal nuovo file RC. 

Bisogna creare DLL di risorse per ogni traduzione che si intende supportare. Ogni 
DLL di risorse deve avere una estensione di file specifica del paese a cui e destinata. I 
primi due caratteri indicano la lingua di destinazione, mentre il terzo carattere indica 
il paese. Se si usa il Resource DLL wizard, questa operazione viene effettuata 
automaticamente. Altrimenti, per ottenere il codice locale per la traduzione 
desiderata, si deve usare il codice seguente: 

/* This callback fills a listbox with the strings and their associated languages and 
countries*/ 

BOOL __stdcall EnumLocalesProc (char* lpLocaleString) 

{ 

AnsiStrmg LocaleName, LanguageName, CountryName; 
LCID lcid; 

lcid = StrToInt ("$" + AnsiString (lpLocaleString) ) ; 
LocaleName = GetLocaleStr (lcid, LOCALE_SABBREVLANGNAME , ""); 
LanguageName = GetLocaleStrdcid, L0CALE_SNAT1VELANGNAME, ""); 
CountryName = GetLocaleStrdcid, L0CALE_SNAT1VECTRYNAME, ""); 
if ( lstrlen (LocaleName. c_str() ) > 0) 

Forml->ListBoxl->ltems->Add(LocaleName + ":" + LanguageName + "-" + CountryName); 
return TRUE; 

} 

/* This call causes the callback to execute for every locale */ 
EnumSystemLocales ( (LOCALE_ENUMPROC)EnumLocalesProc, LCTD_SUPPORTED) ; 

Uso delle DLL di risorse 



L'eseguibile, le DLL e i package (bpls) che costituiscono l'applicazione contengono 
tutte le risorse necessarie. Tuttavia, per sostituire quelle risorse con le versioni 
localizzate, e sufficiente distribuire l'applicazione con DLL di risorse localizzate 
aventi lo stesso nome del file eseguibile, della DLL o del package. 
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Quando l'applicazione viene awiata, controlla la localita del sistema. Se 
l'applicazione trova delle DLL di risorse con lo stesso nome dei file EXE, DLL o BPL 
che utilizza, ne controlla l'estensione. Se questa corrisponde a quella della lingua e 
del paese della localita del sistema, l'applicazione utilizza le risorse contenute nella 
DLL di risorse al posto delle risorse contenute nell'eseguibile, nella DLL o nel 
package.Se non c'e una DLL di risorse corrispondente alia lingua e al paese, 
l'applicazione prova a localizzare la DLL di risorse utilizzando quella corrispondente 
alia lingua della localita. Se non ci sono DLL di risorse corrispondenti alia lingua, 
l'applicazione utilizza le risorse compilate con l'eseguibile, la DLL o il package. 

Se si vuole che la propria applicazione utilizzi una DLL di risorse diversa da quelle 
della localita del sistema, si puo impostare una voce di ridefinizione della localita nel 
registro di Windows. Sotto HKEY_CURRENT_USER\ Software \ Borland \ Locales 
key, bisogna aggiungere il percorso e il nome di file della propria applicazione come 
un valore stringa e impostare il valore dati all'estensione delle proprie DLL di risorse. 
All'avvio, l'applicazione cerchera le risorse DLL con questa estensione prima di 
verificare qual e il sistema locale. L'impostazione di questa voce nel registro permette 
di collaudare le versioni localizzate delle proprie applicazioni senza dover 
modificare la localita del sistema. 

Per esempio, la procedura seguente puo essere utilizzata in un programma di 
impostazione o di installazione per definire il valore della chiave del registro che 
indica la localita da utilizzare durante il caricamento delle applicazioni C++Builder: 

void SetLocalOverrides (char* FileName, char* LocaleOverride) 

{ 

HKEY Key; 

const char* LocaleOverrideKey = "SoftwareWBorlandWLocales"; 
if ( RegOpenKeyEx ( HKEY_CURRENT_USER , LocaleOverrideKey, 0, KEY_ALL_ACCESS, &Key) 
== ERROR_SUCCESS) { 
if (lstrlen(LocaleOverride) == 3) 

RegSetValueExfKey, FileName, 0, REG_SZ, (const BYTE* (LocaleOverride, 4); 
RegCloseKey (Key) ; 

} 

} 

All'interno dell'applicazione, per ottenere la gestione della DLL di risorse attiva si 
deve usare la funzione globale FindResourceHInstance. Ad esempio: 

LoadString(FindResourceHlnstance(Hlnstance) , LDS_AmountDueName, szQuery, sizeof (szQuery) ) ; 

E possibile distribuire una sola applicazione che si adatti automaticamente alia 
localita del sistema sul quale verra eseguita, fornendo semplicemente le DLL di 
risorse appropriate. 

Sostituzione dinamica delle DLL di risorse 



Oltre a localizzare una DLL di risorse in fase di avvio dell'applicazione, e possibile 
cambiare in modo dinamico le DLL di risorse durante l'esecuzione. Per aggiungere 
questa funzionalita alle applicazioni, occorre includere nel progetto la unit Relnit. 
(Relnit e presente nell'esempio Richedit nella directory Examples). Per cambiare 
lingua, si deve chiamare LoadResourceModule, passando la LCID per la nuova lingua, 
e poi chiamare ReinitializeForms. 
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Per esempio, il codice seguente cambia la lingua dell'interfaccia nel Francese: 

const FRENCH = ( SUBLANG_FRENCH « 10) I LANG_FRENCH; 
if (LoadNewResourceModule (FRENCH) ) 
ReinitializeForms ( ) ; 

II vantaggio che deriva da questa tecnica e che vengono usate l'istanza attiva 
dell'applicazione e tutte le sue schede. Non e necessario aggiornare le impostazioni 
del registro e riavviare l'applicazione o riacquisire le risorse richieste 
dall'applicazione, come il login ai database server. 

Quando si cambia la DLL di risorse, le proprieta specificate nella nuova DLL 
sovrascrivono quelle delle istanze attiva della scheda. 

Tutte le modifiche apportate alle proprieta della scheda andranno perdute in fase di 
esecuzione. Una volta caricata la nuova DLL, non vengono ripristinati i valori 
predefiniti. Bisogna evitare di scrivere codice che presuma che gli oggetti della 
scheda vengano reinizializzati al loro stato di avvio, al di la delle differenze dovute 
alia localizzazione. 



Localizzazione delle applicazioni 



Una volta che 1' applicazione e stata internazionalizzata, si possono creare versioni 
localizzate per i diversi mercati esteri in cui si intende distribuirla. 

Localizzazione delle risorse 



In teoria, le risorse vengono isolate in una DLL di risorse contenente i file scheda 
(.dfm per VCL o .xfm per CLX) e in un file di risorse. E possibile aprire le schede 
nell'IDE e tradurre le proprieta pertinenti. 

In un progetto di DLL di risorse non si possono aggiungere o rimuovere componenti. 
Tuttavia, e possibile cambiare le proprieta che possono provocare errori di runtime. 
Per evitare errori, e possibile configurare Object Inspector in modo che visualizzi solo 
le proprieta che possono essere localizzate; per fare cio, fare clic destro nell'Object 
Inspector e utilizzare il menu View per filtrare tutte le categorie di proprieta non 
desiderate. 

E possibile aprire il file RC e tradurre le stringhe rilevanti. A questo scopo, si deve 
usare lo StringTable editor aprendo il file RC con Project Manager. 



Creazione di applicazioni internazionali 16-13 



Localizzazione delle applicazioni 



16-14 Guida alia programmazione 



Capitolo 




Distribuzione di applicazioni 

Una volta che l'applicazione C++Builder e pienamente funzionante, la si puo 
distribuire. Cioe, e possibile renderla disponibile ad altri utenti affinche la utilizzino. 
Per distribuire un'applicazione da utilizzare su altri computer, occorre effettuare una 
serie di operazioni, in modo che essa risulti completamente funzionale. II numero di 
operazioni necessarie varia da un'applicazione all'altra, a seconda del tipo. Le 
seguenti sezioni trattano alcune problematiche da prendere in esame quando si 
distribuiscono i vari tipi di applicazioni: 

• Distribuzione di applicazioni generiche 

• Distribuzione di applicazioni CLX 

• Distribuzione di applicazioni database 

• Distribuzione di applicazioni Web 

• Programmazione per ambienti di destinazione diversi 

• Requisiti per la licenza d'uso del software 

Le informazioni incluse in queste sezioni valgono per la distribuzione di applicazioni 
in ambiente Windows. 



Distribuzione di applicazioni generiche 



Oltre al file eseguibile, un'applicazione puo richiedere una certo numero di file di 
supporto, come DLL, file package e applicazioni di ausilio. Inoltre, il registro di 
Windows puo aver bisogno di contenere dati su un'applicazione, dalla specificazione 
della dislocazione dei file di supporto alle semplici impostazioni del programma. II 
processo di copia dei file di un'applicazione su un computer e di registrazione delle 
impostazioni necessarie nel registro puo essere automatizzato da un programma di 
installazione, come InstallShield Express. I principali aspetti connessi alia 
distribuzione dei programmi, comuni a quasi tutti i tipi di applicazione, sono: 

• Uso di programmi di installazione 

• Identificazione dei file dell'applicazione 



Distribuzione di applicazioni 17-1 



Distribuzione d i applicazioni generiche 

Le applicazioni C++Builder che accedono ai database e quelle che funzionano su 
Web richiedono ulteriori operazioni, oltre a quelle che valgono per le applicazioni 
generiche. Per ulteriori informazioni sull'installazione di applicazioni database, 
consultare "Distribuzione di applicazioni database" a pagina 17-6. Per maggiori 
informazioni sull'installazione di applicazioni Web, consultare "Distribuzione di 
applicazioni Web" a pagina 17-10. Per maggiori informazioni sull'installazione di 
controlli ActiveX, consultare "Distribuzione di un controllo ActiveX su Web" a 
pagina 43-17. Per informazioni sulla distribuzione di applicazioni CORBA, il 
manuale VisiBroker Installation and Administration Guide. 

Uso di programmi di installazione 



Le applicazioni C++Builder costituite semplicemente da un file eseguibile sono facili 
da installare su un computer di destinazione. Basta copiare il file eseguibile sul 
computer. Le applicazioni piu complesse, composte da molti file, richiedono, invece, 
procedure di installazione piu articolate. Queste applicazioni richiedono, pertanto, 
programmi di installazione dedicati. 

I kit di installazione automatizzano il processo di creazione dei programmi di 
installazione, spesso senza che sia necessario scrivere alcuna riga di codice. I 
programmi creati con questi kit eseguono varie operazioni inerenti all'installazione 
delle applicazioni C++Builder, fra cui la copia del file eseguibile e dei file di supporto 
sul computer di destinazione la creazione delle voci nel registro di Windows e 
l'installazione del Borland Database Engine per le applicazioni database che fanno 
uso di BDE. 

InstallShield Express e un kit di strumenti per l'impostazione che viene abbinato a 
C++Builder. InstallShield Express e certificato per essere usato con C++Builder e con 
Borland Database Engine. Si basa sulla tecnologia di Windows Installer (MSI). 

InstallShield Express non viene installato automaticamente durante l'installazione di 
C++Builder, e deve quindi essere installato manualmente se lo si vuole utilizzare per 
creare programmi di installazione. Per installare InstallShield Express, occorre 
eseguire il programma di installazione dal CD di C++Builder. Per maggiori 
informazioni sull'uso di InstallShield Express per creare programmi di installazione, 
consultare la Guida in linea di InstallShield Express. 

Sono disponibili altri kit per l'installazione. Tuttavia, se si distribuisconoo 
applicazioni database BDE, si dovrebbero usare solo quei kit che si basano sulla 
tecnologia MSI o quelli certificati per la distribuzione di Borland Database Engine. 

Identificazione dei file dell'applicazione 

Oltre al file eseguibile, con l'applicazione puo essere necessario distribuire un certo 
numero di altri file. 

• File package 

• File di applicazione 

• Moduli di fusione 

• Controlli ActiveX 
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File di applicazione 

Con un'applicazione potrebbe essere necessario distribuire i seguenti tipi di file. 



Tabella 17.1 Filedi applicazione 



Tipo 


Estensione 


File di 


.exe e .dll 


programma 




File di 


..bpl, .bpi, e .lib 


applicazione 




File della 


.hip, .cnt, e .toe (se utilizzato) o tutti gli altri file di Guida supportati 


Guida 


dall'applicazione 


ActiveX files 


.ocx (a volte supportati da una DLL) 


File di tabelle 


.dbf, .mdx, .dbt, .ndx, .db, .px, .y*, .x*, .mb, .val, .qbe, .gd* 


locali 



File package 

Se l'applicazione usa dei package di runtime, e necessario che essi vengano 
distribuiti insieme all'applicazione. InstallShield Express gestisce l'installazione dei 
file package nello stesso modo delle DLL, copiando i file ed apportando le necessarie 
modifiche nel registro di Windows. Per la distribuzione di package di esecuzione con 
strumenti di installazione basati su MSI, tra cui InstallShield Express, e possibile 
anche utilizzare moduli di fusione. Per i dettagli, vedere la sezione successiva. 

Borland consiglia di installare i file package di runtime forniti da Borland nella 
directory Windows \ System. Questa directory serve come dislocazione comune, in 
modo che piu applicazioni possano accedere a un'unica istanza dei file. Si consiglia 
di installare nella stessa directory dell'applicazione anche i package creati. Devono 
essere distribuiti solo i file .bpl. 

Se si distribuiscono package con applicazioni CLX, e necessario includere clx60.bpl 
invece di vcl60.bpl. 

Se i package vengono distribuiti ad altri sviluppatori, fornire i file .bpl, .bpi, e .lib (se 
si vuole consentire il link statico con i propri package). 

Moduli di fusione 

InstallShield Express 3.0 si basa sulla tecnologia di Windows Installer (MSI). Ecco 
perche C++Builder include i moduli di fusione. I moduli di fusione forniscono un 
metodo standard che e possibile utilizzare per distribuire con le applicazioni codice 
condiviso, file, risorse, voci del file di Registro e logica di installazione come un 
singolo file composto. E possibile utilizzare i moduli di fusione per la distribuzione 
di package di esecuzione con strumenti di installazione basati su MSI tra cui 
InstallShield Express. 

Le librerie di esecuzione contengono alcune interdependenze a causa del modo in cui 
vengono assemblate. II risultato e che quando un package viene aggiunto a un 
progetto di installazione, lo strumento di installazione aggiunge automaticamente o 
segnala una dipendenza da uno o piu packages. Per esempio, se si aggiunge il 
modulo di fusione VCLInternet a un progetto di installazione, lo strumento di 
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installazione dovrebbe anche aggiungere automaticamente o segnalare una 
dipendenza dai moduli VCLDatabase e StandardVCL. 

Le dipendenze per ciascun modulo di fusione sono elencate nella tabella seguente. I 
diversi strumenti di installazione possono reagire a queste dipendenze in modo 
diverse InstallShield for Windows Installer aggiunge automaticamente i moduli 
necessari se e in grado di individuarli. Altri strumenti possono segnalare 
semplicemente una dipendenza oppure generare un malfunzionamento di creazione 
se nel progetto non sono inclusi tutti i moduli necessari. 

Tabella 17.2 Moduli di fusione e rispettive dipendenze 



ADU 


aaortloU.Dpi 


UatabaseKl L, baseKlL 


BaseClientDataSet 


cds60.bpl 


DatabaseRTL, BaseRTL, DataSnap, 
dbExpress 


BaseRTL 


rtl60.bpl 


No dependencies 


BaseVCL 


vcl60.bpl, vclx60.bpl 


BaseRTL 


BDEClientDataSet 


bdecds60.bpl 


BaseClientDataSet, DataBaseRTL, BaseRTL, 
DataSnap, dbExpress, BDERTL 


BDEInternet 


inetdbbde60.bpl 


Internet, DatabaseRTL, BaseRTL, BDERTL 


BDERTL 


bdertl60.bpl 


DatabaseRTL, BaseRTL 


DatabaseRTL 


dbrtl60.bpl 


BaseRTL 


DatabaseVCL 


vcldb60.bpl 


BaseVCL, DatabaseRTL, BaseRTL 


DataSnap 


dsnap60.bpl 


DatabaseRTL, BaseRTL 


DataSnapConnection 


dsnapcon60.bpl 


DataSnap, DatabaseRTL, BaseRTL 


DataSnapCorba 


dsnapcrba60.bpl 


DataSnapConnection, DataSnap, 
uataDaseKlL, baseKlL, nasevCL 


DataSnapEntera 


dsnapent60.bpl 


DataSnap, DatabaseRTL, BaseRTL, 
BaseVCL 


DBCompatVCL 


vcldbx60.bpl 


DatabaseVCL, BaseVCL, BaseRTL, 
DatabaseRTL 


dbExpress 


dbexpress60.bpl 


DatabaseRTL, BaseRTL 


dbExpressClientDataSet 


dbxcds60.bpl 


BaseClientDataSet, DataBaseRTL, BaseRTL, 
DataSnap, dbExpress 


DBXInternet 


inetdbxpress60 .bpl 


Internet, DatabaseRTL, BaseRTL, 
dbExpress, DatabaseVCL, BaseVCL 


DecisionCube 


dss60.bpl 


TeeChart, BaseVCL, BaseRTL, 
DatabaseVCL, DatabaseRTL, BDERTL 


FastNet 


nmfast60.bpl 


BaseVCL, BaseRTL 


InterbaseVCL 


ibxpress60.bpl 


BaseClientDataSet, BaseRTL, BaseVCL, 
DatabaseRTL, DatabaseVCL, DataSnap, 
dbExpress 


Internet 


inet60.bpl, inetdb60.bpl 


DatabaseRTL, BaseRTL 


InternetDirect 


indy60.bpl 


BaseVCL, BaseRTL 


Office2000Components 


dcloffice2k60.bpl 


DatabaseVCL, BaseVCL, DatabaseRTL, 
BaseRTL 


QuickReport 


qrpt60.bpl 


BaseVCL, BaseRTL, BDERTL, DatabaseRTL 
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Tabella 17.2 Moduli di fusione e rispettive dipendenze (continua) 



MaHiiIa Hi fiici/\na 
IVIUQUIO ui lusionc 


DDI infhica 
DrL INUIUoc 


ninQnHan7Q 
Ulpc ilUcll^c 


SampleVCL 


vclsmp60.bpl 


BaseVCL, BaseRTL 


TeeChart 


tee60.bpl, teedb60.bpl, 
teeqr60.bpl, teeui60.bpl 


BaseVCL, BaseRTL 


VCLIE 


vclie60.bpl 


BaseVCL, BaseRTL 


VisualCLX 


visualclx60.bpl 


BaseRTL 


VisualDBCLX 


visualdbclx60.bpl 


BaseRTL, DatabaseRTL, VisualCLX 


WebDataSnap 


webdsnap60.bpl 


XMLRTL, Internet, DataSnapConnection, 
DataSnap, DatabaseRTL, BaseRTL 


WebSnap 


websnap61.bpl, 
vcljpg60.bpl 


WebDataSnap, XMLRTL, Internet, 
DataSnapConnection, DataSnap, 
DatabaseRTL, BaseRTL, BaseVCL 


XMLRTL 


xmlrtl60.bpl 


Internet, DatabaseRTL, BaseRTL 



Controlli ActiveX 

Determinati componenti abbinati a C++Builder sono i controlli ActiveX. II wrapper 
del componente viene collegato al file eseguibile dell'applicazione (o a un package di 
runtime), insieme alia quale deve essere distribuito anche il file .ocx per il 
componente. Questi componenti comprendono: 

• Chart FX, copyright SoftwareFX Inc. 

• VisualSpeller Control, copyright Visual Components, Inc. 

• Formula One (spreadsheet), copyright Visual Components, Inc. 

• First Impression (VtChart), copyright Visual Components, Inc. 

• Graph Custom Control, copyright Bits Per Second Ltd. 

I controlli ActiveX creati dal programmatore devono essere registrati sul computer di 
distribuzione prima di poter essere usati. Programmi di installazione come 
InstallShield Express automatizzano questo processo di registrazione. Per registrare 
manualmente un controllo ActiveX, scegliere il comando Run I ActiveX Server 
nell'IDE, usare l'applicazione demo TRegSvr oppure il programma di utilita 
REGSRV32.EXE di Microsoft (non incluso nelle versioni di Windows 9x). 

Con un'applicazione devono essere distribuite anche le DLL che supportano i 
controlli ActiveX. 

Applicazioni di ausilio 

Le applicazioni di ausilio sono programmi distinti senza i quali l'applicazione 
C++Builder e parzialmente o completamente impossibilitata a funzionare. Queste 
applicazioni possono essere quelle fornite col sistema operativo, da Borland oppure 
prodotti di terze parti. Un esempio di applicazione di ausilio e il programma di 
utilita Server Manager di InterBase, che amministra i database, gli utenti e la 
sicurezza di InterBase. 

Se un'applicazione dipende da un programma di ausilio, bisogna accertarsi di 
distribuirlo con l'applicazione, se possibile. La distribuzione di programmi di ausilio 
possono essere regolata da accordi di licenza per la ridistribuzione. Per informazioni 
specifiche, consultare la documentazione dell'applicazione di ausilio. 
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Ubicazione delle DLL 

I file DLL usati da una singola applicazione possono essere installati nella sua stessa 
directory. Le DLL che verranno usate da piu applicazioni devono essere installate in 
una posizione accessibile alle diverse applicazioni. Una convenzione diffusa per la 
sistemazione di tali DLL comunitarie e quella di collocarle nella directory Windows o 
Windows \ System. Un metodo ancora migliore consiste nel creare un'apposita 
directory per i file DLL comuni, simile al metodo adottato per l'installazione di 
Borland Database Engine. 

Distribuzione di applicazioni CLX 



Per distribuire un'applicazione CLX in ambiente Windows, seguire le stesse 
procedure usate per la distribuzione delle normali applicazioni. Per informazioni 
sulla distribuzioe di applicazioni generiche, consultare "Distribuzione di 
applicazioni generiche" a pagina 17-1. Per informazioni sull'installazione di 
applicazioni database CLX, consultare "Distribuzione di applicazioni database" a 
pagina 17-6. 

Quando si distribuiscono applicazioni CLX in ambiente Windows, e necessario 
includere con l'applicazione qtintf.dll in modo da includere il runtime CLX. Se si 
distribuiscono package con applicazioni CLX, e necessario includere clx60.bpl invece 
che vcl60.bpl. 

Per informazioni sulla scrittura di applicazioni a CLX, consultare il Capitolo 14, 
"Sviluppo di applicazioni multipiattaforma". 

Distribuzione di applicazioni database 



Le applicazioni che accedono ai database implicano, al di la della copia del file 
eseguibile dell'applicazione sul computer host, particolari considerazioni 
sull'installazione. Spesso l'accesso al database viene gestito da un motore di database 
distinto, i cui file non possono essere collegati nel file eseguibile dell'applicazione. I 
file di dati, quando non sono creati in anticipo, devono essere resi disponibili 
all'applicazione. I database multi-tier richiedono anche una gestione piu specialistica 
dell'installazione, in quanto i file che costituiscono l'applicazione vengono 
normalmente collocati su piu computer. 

Poiche sono supportate varie tecnologie di database (ADO, BDE, dbExpress e 
InterBase Express), i requisiti di distribuzione sono diversi per ognuna di esse. 
Indipendentemente dalla tecnologia utilizzata, e necessario accertarsi che sul sistema 
su cui si prevede di eseguire l'applicazione database sia installato il software lato 
client. ADO, BDE, dbExpress e InterBase Express necessitano anche di driver per 
interagire con il software lato client del database. 

Informazioni specifiche su come distribuire applicazioni database dbExpress, BDE e 
multi-tier sono riportate nelle seguenti sezioni: 

• Distribuzione di applicazioni database dbExpress 
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• Distribuzione di applicazioni BDE 

• Distribuzione di applicazioni database multi-tier (DataSnap) 

Le applicazioni database che utilizzano dataset client come TClientDataSet o provider 
di dataset richiedono l'inclusione di midaslib.dcu e di crtl.dcu (per il collegamento 
statico nel caso si distribuisca un eseguibile indipendente ); se si sta creando un 
package dell'applicazione (con l'eseguibile e tuue le DLL necessarie), si deve 
includere Midas.dll. 

Se si distribuiscono applicazioni database che utilizzano ADO, e necessario accertarsi 
che sul sistema su cui si prevede di eseguire l'applicazione sia installato MDAC 
versione 2.1 o successiva. MDAC viene installato automaticamente con software 
come Windows 2000 o Internet Explorer versione 5 o successiva. E necessario anche 
assicurarsi che sul client siano installati i driver per il server di database a cui ci si 
vuole collegare. Non sono necessarie altre operazioni per la distribuzione. 

Se si distribuiscono applicazioni database che utilizzano InterBase Express, e 
necessario accertarsi che sul sistema su cui si prevede di eseguire l'applicazione sia 
installato il client InterBase. InterBase richiede che gd32.dll e interbase.msg siano 
situati in una directory accessibile. Non sono necessarie altre operazioni. I 
componenti InterBase Express comunicano direttamente con l'API di InterBase 
Client e non richiedono driver aggiuntivi. Per ulteriori informazioni, fare riferimento 
al documento Embedded Installation Guide reperibile sul sito Web di Borland. 

Oltre alle tecnologie qui descritte, per consentire l'accesso ai database da parte delle 
applicazioni C++Builder e possibile usare motori di database di produttori terzi. Per 
quanto riguarda i diritti di ridistribuzione, l'installazione e la configurazione, 
consultare la documentazione fornita col motore di database o il rivenditore. 

Distribuzione di applicazioni database dbExpress 



dbExpress e un gruppo di driver nativi leggeri che consentono un accesso rapido alle 
informazioni dei database. dbExpress supporta lo sviluppo multipiattaforma poiche 
sono disponibili anche su Linux. Per ulteriori informazioni sull'utilizzo dei 
componenti dbExpress, fare riferimento al Capitolo 26, "Uso di dataset 
unidirezionali". 

Le applicazioni dbExpress possono essere distribuite o come file eseguibile 
indipendente o come file eseguibile che include le DLL associate dei driver 
dbExpress. 

Per distribuire le applicazioni dbExpress come file eseguibili indipendenti, i file 
oggetto dbExpress devono essere collegati nell'eseguibile in modo statico. 
L'operazione viene condotta includendo i seguenti file DCU, inclusi nella directory 
lib: 

Tabella 17.3 Distribuzione di dbExpress come eseguibile indipendente 
Unit di Database Da includere in 

dbExpINT Applicazioni che si collegano a database InterBase 

dbExpORA Applicazioni che si collegano a database Oracle 
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Tabella 17.3 Distribuzione di dbExpress come eseguibile indipendente (continua) 
Unit di Database Da includere in 

dbExpDB2 Applicazioni che si collegano a database DB2 

dbExpMYS Applications connecting to MySQL 3.22.x 

dbExpMYSQL Applicazioni che si collegano a database MySQL 3.23.x 

crtl richiesto da tutti gli eseguibili che usano dbExpress 

MidasLib Richiesto da eseguibili dbExpress che utilizzano dataset client come 

TClientDataSet 



Nel caso di applicazioni database che utilizzano Informix non e possibile distribuire 
un eseguibile indipendente. Si deve invece distribuire un file eseguibile con la DLL 
del driver dbexpinf.dll (elencata nella tabella seguente). 

Se non si sta distribuendo un eseguibile indipendente, e possibile distribuire assieme 
all'eseguibile i driver dbExpress associati e le DLL di DataSnap. La seguente tabella 
elenca le DLL necessarie e quando includerle: 

Tabella 17.4 Distribuzione dbExpress con DLL di driver 

DLL di database Da distribuire in 

dbexpinf.dll Applicazioni che si connettono a database Informix 

dbexpint.dll Applicazioni che si connettono a database InterBase 

dbexpora.dll Applicazioni che si connettono a database Oracle 

dbexpdb2.dll. Applicazioni che si connettono a database DB2 

dbexpmys.dll Applicazioni che si connettono a database MySQL 3.22.x 

dbexpmysql.dll Applicazioni che si connettono a database MySQL 3.23.x 

Midas.dll Richiesta da applicazioni database che utilizzano dataset client 



Distribuzione di applicazioni BDE 



Borland Database Engine (BDE) definisce una vasta API per interagire con i database. 
Fra tutti i meccanismi per l'accesso ai dati, BDE e quello che supporta la piu vasta 
gama di funzioni e dispone di numerosi con programmi di utilita di supporto. E la 
migliore soluzione per operare con dati in tabelle Paradox o dBASE. 

L'accesso al database per un'applicazione viene fornito da diversi motori di database. 
Un'applicazione puo usare BDE o un motore di database di produttori terzi. Per 
consentire l'accesso nativo ai sistemi di database SQL vengono forniti gli SQL Links 
(non disponibili in tutte le edizioni). Le seguenti sezioni descrivono l'installazione 
degli elementi di accesso al database di un'applicazione: 

• Borland Database Engine 

• SQL Links 
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Borland Database Engine 

Affinche i componenti dati standard C++Builder abbiano accesso al database, deve 
essere presente e accessibile Borland Database Engine (BDE). Per i diritti specif ici e le 
limitazioni sulla ridistribuzione di BDE, consultare il documento BDEDEPLOY. 

Borland consiglia l'uso di InstallShield Express (o di un altro programma di 
installazione certificato) per installare BDE. InstallShield Express effettuera gli 
inserimenti necessari nel registro e definira tutti gli alias di cui l'applicazione pud 
avere bisogno. L'uso di un programma di installazione certificato per la distribuzione 
dei file BDE e dei suoi subset e importante in quanta: 

• L'installazione non corretta di BDE o dei suoi subset puo provocare errori 
nell'esecuzione delle applicazioni che usano BDE. Tali applicazioni includono non 
solo prodotti Borland, ma molti programmi di produttori terzi che usano BDE. 

• In ambiente Windows a 32 bit come 95 /NT e versioni successive, le informazioni 
sulla configurazione di BDE sono memorizzate nel registro di Windows anziche 
nei file .ini, come avveniva in Windows a 16 bit. L'inserimento e la cancellazione 
dei dati per l'installazione e la disinstallazione sono operazioni complesse. 

E possibile installare solo la parte di BDE di cui un'applicazione ha realmente 
bisogno. Per esempio, se un'applicazione usa solo tabelle Paradox, e necessario 
installare solo quella parte di BDE necessaria per accedere a tali tabelle. Cio per 
un'applicazione vuol dire minore necessita di spazio su disco. I programmi di 
installazione certificati, come InstallShield Express, sono in grado di eseguire 
installazioni parziali di BDE. Assicurarsi di lasciare i file BDE di sistema che non 
vengono usaii dall'applicazione distribuita, ma che sono necessari per altri 
programmi. 

SQL Links 

SQL Links fornisce i driver che collegano un'applicazione (tramite Borland Database 
Engine) con il software client per un database SQL. Per i diritti specifici e le 
limitazioni sulla ridistribuzione di SQL Links, consultare il documento DEPLOY. 
Come awiene per Borland Database Engine (BDE), SQL Links deve essere distribuito 
usando InstallShield Express (o un altro programma di installazione certificato). 

SQL Links collega solo BDE al software client, non al database SQL stesso. E sempre 
necessario installare il software client per il sistema di database SQL usato. Per 
maggiori informazioni sull'installazione e la configurazione del software client, 
consultare la documentazione del sistema di database SQL o il relativo produttore. 

La Tabella 17.5 mostra i nomi del driver e dei file di configurazione utilizzati da SQL 
Links per la connessione ai diversi sistemi di database SQL. Questi file vengono 
forniti con SQL Links e sono ridistribuibili secondo quanto previsto dall'accordo di 
licenza d'uso di C++Builder. 

Tabella 17.5 File software del client di database 
Produttore File ridistribuibili 

Oracle 7 SQLORA32.DLL and SQL_ORA.CNF 

Oracle 8 SQLORA8.DLL and SQL_ORA8.CNF 
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Tabella 17.5 File software del client di database (continua) 
Produttore File ridistribuibili 

Sybase Db-Lib SQLSYB32.DLL and SQL_SYB.CNF 

Sybase Ct-Lib SQLSSC32.DLL and SQL_SSC.CNF 

Microsoft SQL Server SQLMSS32.DLL and SQLJVISS.CNF 
Informix 7 SQLINF32.DLL and SQLJNF.CNF 

Informix 9 SQLINF9.DLL and SQLJNF9.CNF 

DB/2 2 SQLDB232.DLL and SQLJ3B2.CNF 

DB/2 5 SQLDB2V5.DLL and SQL_DB2V5.CNF 

InterBase SQLINT32.DLL and SQLJNT.CNF 

SQL Links deve essere installato usando InstallShield Express o un altro programma 
di installazione certificate Per informazioni specifiche riguardanti l'installazione e la 
configurazione di SQL Links, consultare il file di Guida SQLLNK32.HLP, installato 
per impostazione predefinita nella directory principale di BDE. 

Distribuzione di applicazioni database multi-tier (DataSnap) 

DataSnap fornisce alle applicazioni C++Builder le capacita di database multi-tier, 
consentendo alle applicazioni client di collegarsi ai provider in un application server. 

Installare DataSnap insieme a un'applicazione multi-tier utilizzando InstallShield 
Express (o un'altro programma di installazione certificato da Borland). Per i dettagli 
relativi ai file che occorre ridistribuire con un'applicazione, consultare il documento 
DEPLOY, presente nella directory principale di C++Builder. Consultare inoltre il 
documento REMOTE per informazioni relative a quali file di DataSnap e possibile 
ridistribuire e secondo quali modalita. 



Distribuzione di applicazioni Web 



Alcune applicazioni C++Builder sono progettate per essere eseguite sul World Wide 
Web, come quelle in formato di DLL Server-side Extension (ISAPI e Apache), le 
applicazioni CGI e le ActiveForms. 

Le operazioni per la distribuzione delle applicazioni Web sono analoghe a quelle 
previste per le applicazioni generiche, con la differenza che in questo caso i file 
dell'applicazione devono essere distribuiti sul server Web. Per informazioni 
sull'installazione delle applicazioni generiche, vedere "Distribuzione di applicazioni 
generiche" a pagina 17-1. Per informazioni sulla distribuzione di applicazioni 
database sul Web, consultare "Distribuzione di applicazioni database" a pagina 17-6. 

Ecco alcune particolari considerazioni per la distribuzione di applicazioni Web: 

• Nel caso di applicazioni database BDE, Borland Database Engine (o un motore di 
database alternative) viene installato insieme ai file dell'applicazione sul server 
Web. 
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• Nel caso di applicazioni db Express, le DLL di dbExpress devono essere incluse nel 
percorso di ricerca. Nel caso sia incluso, il driver dbExpress viene installato 
insieme ai file dell'applicazione sul server Web. 

• Le politiche di sicurezza per le directory dovrebbero essere impostate in modo che 
l'applicazione possa accedere a tutti i file di database necessari. 

• La directory contenente un'applicazione deve avere attributi di lettura e di 
esecuzione. 

• L'applicazione non deve usare percorsi definiti a livello di codice per l'accesso ai 
file del database o agli altri file. 

• L'ubicazione di un controllo ActiveX viene indicata dal parametro CODEBASE del 
tag HTML <OBJECT>. 

La distribuzione su Apache e trattata nel paragrafo successivo. 

Distribuzione su server Apache 



WebBroker supporta la versione 1.3.9 e successive di Apache per DLL e applicazioni 
CGI. 

Moduli e applicazioni vengono abilitati e configurati modificando il file httpd.conf di 
Apache (di solito situato nella directory \conf dell'installazione di Apache). 

Abilitazione dei moduli 

Le DLL dovrebbero essere ubicate fisicamente nella subdirectory dei moduli di 
Apache. 

Pe abilitare un modulo e necessario apportare due modifiche al file httpd.conf. 

1 Aggiungere un elemento LoadModule in modo da consentire ad Apache di 
individuare e caricare la DLL. Ad esempio: 

LoadModule MyApachejnodule modules/Projectl.dll 

2 Aggiungere un elemento resource locator (puo essere aggiunto in un punto 
qualsiasi del file httpd.conf dopo l'elemento LoadModule). Ad esempio: 

# Sample location specification for a project named projectl. 

<Location /projectl> 

SetHandler projectl-handler 

</Location> 

Questa modifica consente di passare al modulo di Apache tutte le richieste per 
l'indirizzo http:/ / www.somedomain.com/projectl. 

La direttiva SetHandler specifica l'applicazione Web server che gestisce la richiesta. 
L'argomento SetHandler dovrebbe essere impostato al valore della variabile globale 
ContentType. 
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Applicazioni CGI 

Se si creano applicazioni CGI, la directory fisica (specificata nella direttiva Directory 
del file httpd.conf) deve avere l'opzione ExecCGI e la clausola SetHandler impostate 
in modo da consentire l'esecuzione di programmi e poter pertanto eseguire la 
procedura CGI. Per essere certi che le autorizzazioni siano configurate correttamente, 
utilizzare la direttiva Alias con entrambe le opzioni ExecCGI e SetHandler abilitate. 

Un metodo alternativo consiste nell'utilizzare la direttiva ScriptAlias (senza Options 
ExecCGI), ma l'utilizzo di questo metodo potrebbe impedire all'applicazione CGI di 
leggere un qualsiasi file incluso nella directory ScriptAlias. 

La seguente riga di httpd.conf e un esempio di come utilizzare la direttiva Alias per 
creare sul proprio server una directory virtuale e contrassegnare l'esatta ubicazione 
dello script CGI: 

Alias/MyWeb/"c:/httpd/docs/MyWeb/" 

Cio consente di soddisfare richieste del tipo /MyWeb/mycgi . exe eseguendo lo script 

c : \httpd\docs\MyWeb\mycgi . exe. 

E possibile anche impostare Options ad All o a ExecCGI utilizzando la direttiva 
Directory inclusa in httpd.conf. La direttiva Options controlla quali funzioni del 
server sono disponibili in una particolare directory. 

Le direttive Directory sono utilizzate per includere un set di direttive che hanno 
valore per la directory in oggetto e per le directory in essa contenute. Di seguito e 
riportato un esempio della direttiva Directory: 

<Directory "c : /httpd/docs/MyWeb"> 
AllowOverride None 
Options ExecCGI 
Order allow, deny 
Allow from all 
</Directory> 

In questo esempio, Options e impostato a ExecCGI, permettendo cosi l'esecuzione di 
procedure CGI nella directory MyWeb. La clausola AddHandler consente ad Apache 
di sapere che i file con estensioni quali as exe e cgi sono script CGI (eseguibili) 

Apache viene eseguito in locale sul server, all'interno dell'account specificato nella 
direttiva User nel file httpd.conf. Accertarsi che l'utente abbia gli opportuni diritti 
per accedere alle risorse necessarie all'applicazione. 

Per ulteriori informazioni sulla distribuzione, consultare il file LICENSE di Apache, 
incluso nella distribuzione del software. Per ulteriori configurazioni di Apache, 
consultare il sito Web Apache all'indirizzo www.apache.org. 

Programmazione per ambienti di destinazione diversi 



Data la natura dei vari ambienti di sistema operativo, vi sono diversi fattori che 
variano a seconda delle preferenze dell'utente o della configurazione. I seguenti 
fattori possono avere effetti su un'applicazione distribuita in un altro computer: 
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• Risoluzione dello schermo e numero di colori 

• Font 

• Versioni del sistema operativo 

• Applicazioni di ausilio 

• Ubicazione delle DLL 

Risoluzione dello schermo e numero di colori 



Le dimensioni del desktop e il numero di colori disponibili su un computer sono 
configurabili e dipendono dall'hardware installato. Questi attributi saranno 
probabilmente diversi a seconda che si tratti dei computer di distribuzione o di quelli 
di sviluppo. 

L'aspetto di un'applicazione (finestra, oggetto e dimensioni del font) su computer 
configurati per risoluzioni di schermo differenti puo essere gestito in vari modi: 

• Progettare l'applicazione per la risoluzione piu bassa prevista (normalmente, 
640x480). Non effettuare particolari operazioni per ridimensionare dinamicamente 
gli oggetti in modo da renderli proporzionali al display dello schermo del 
computer host. Visivamente gli oggetti appariranno tanto piu piccoli quanta piu 
alta sara la risoluzione impostata. 

• Progettare adottando qualsiasi risoluzione dello schermo sul computer di 
sviluppo e, in fase di esecuzione, ridimensionare dinamicamente tutte le schede e 
gli oggetti in modo proporzionale alia differenza tra la risoluzione dello schermo 
dei computer di sviluppo e quella dei computer di distribuzione (un rapporto 
della differenza di risoluzione dello schermo). 

• Progettare utilizzando qualsiasi risoluzione dello schermo sul computer di 
sviluppo e, in fase di esecuzione, ridimensionate dinamicamente solo le schede 
dell'applicazione. A seconda della dislocazione dei controlli visuali sulle schede, 
cio puo richiedere che possa essere effettuato lo scorrimento delle schede perche 
l'utente sia in grado di accedere a tutti i relativi controlli. 

Considerazioni sul ridimensionamento non dinamico 

Se le schede e i controlli visuali che costituiscono un'applicazione non vengono 
ridimensionati dinamicamente in fase di esecuzione, occorre progettare gli aspetti 
che costituiscono l'applicazione per la risoluzione piu bassa. Altrimenti, le schede di 
un'applicazione che funzionano su un computer configurato per una risoluzione 
dello schermo piu bassa di quella del computer di sviluppo potrebbe oltrepassare i 
margini dello schermo. 

Per esempio, se il computer di sviluppo e impostata per una risoluzione di 1024x768 
e una scheda viene progettata con una larghezza di 700 pixel, la scheda non risultera 
del tutto visibile all'interno del desktop su un computer configurato per una 
risoluzione di 640x480. 

Considerazioni sul ridimensionamento dinamico di schede e controlli 

Se le schede e i controlli visuali di un'applicazione vengono ridimensionati in modo 
dinamico, bisogna adattare tutte le fasi del processo di ridimensionamento per 
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assicurare un aspetto ottimale dell'applicazione sotto tutte le possibili risoluzioni 
dello schermo. Quando si ridimensionano dinamicamente gli elementi visuali di 
un'applicazione, occorre considerare i seguenti fattori: 

• II ridimensionamento delle schede e dei controlli visuali viene effettuato con un 
rapporto calcolato confrontando la risoluzione dello schermo del computer di 
sviluppo con quella del computer su cui l'applicazione viene installata. Usare una 
costante per rappresentare una dimensione della risoluzione dello schermo sul 
computer di sviluppo: l'altezza o la larghezza, in pixel. Ricavare la stessa 
dimensione per il computer dell'utente in fase di esecuzione usando la proprieta 
TScreen::Height o TScreen::Width . Dividere il valore ottenuto per il computer di 
sviluppo per il valore del computer dell'utente; in questo modo, si otterra il 
rapporto della differenza tra le risoluzioni dello schermo dei due computer. 

• Ridimensionare gli elementi visuali dell'applicazione (schede e controlli) 
riducendo o aumentando le dimensioni degli elementi e la loro posizione sulle 
schede. Questo ridimensionamento risulta proporzionale alia differenza tra la 
risoluzione dello schermo sul computer di sviluppo e quella del computer 
dell'utente. Ridimensionare e riposizionare automaticamente i controlli visuali 
sulle schede impostando la proprieta TCustomForm::Scaled a true e chiamando il 
metodo TWinControl::ScaleBy (oppureTWidgetControl.ScaleBy nel caso di 
applicazioni mutipiattaforma). II metodo ScaleBy, comunque, non modifica 
l'altezza e la larghezza della scheda. Per eseguire questa operazione manualmente, 
basta moltiplicare i valori attivi delle proprieta Height e Width per il rapporto della 
differenza tra le risoluzioni degli schermi. 

• I controlli su una scheda possono essere ridimensionati manualmente, anziche 
automaticamente, con il metodo TWinControl::ScaleBy (oppure 
TWidgetControl.ScaleBy nel caso di applicazioni multipiattaforma), referenziando 
ciascun controllo visuale in un ciclo e impostandone dimensioni e posizione. I 
valori delle proprieta Height e Width dei controlli visuali vanno moltiplicati per il 
rapporto della differenza tra le risoluzioni degli schermi. Riposizionare i controlli 
visuali in modo proporzionale alia differenza delle risoluzione degli schermi 
moltiplicando i valori delle proprieta Top e Left per lo stesso rapporto. 

• Se un'applicazione viene progettata su un computer configurato per una 
risoluzione piu alta di quella del computer dell'utente, le dimensioni dei font 
saranno ridotte proporzionalmente nel processo di ridimensionamento dei 
controlli visuali. Se la dimensione del font in fase di progettazione e troppo 
piccola, il font ridimensionato in fase di esecuzione potrebbe risultare non 
leggibile. Ad esempio, la dimensione predefinita del font di una scheda e 8. Se il 
computer di sviluppo ha una risoluzione pari a 1024x768 e quello dell'utente una 
risoluzione pari a 640x480, le dimensioni del controllo visuale verranno ridotte di 
un fattore 0,625 (640 / 1024 = 0,625). La dimensione originale del font di 8 verra 
ridotta a 5 (8 * 0,625 = 5). II testo nell'applicazione apparira irregolare e illeggibile 
quando verra visualizzato con un font ridotto. 

• Alcuni controlli visuali, come TLabel e TEdit, vengono ridimensionati 
dinamicamente quando si modificano le dimensioni del font per il controllo. Cio 
puo avere effetti sulle applicazioni distribuite quando le schede e i controlli 
vengono ridimensionati in modo dinamico. II ridimensionamento del controllo 
dovuto alia modifica delle dimensioni del font viene sommato alia modifica delle 
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dimensioni dovuta al ridimensionamento proporzionale per le risoluzioni degli 
schermi. Questo effetto viene compensato impostando la proprieta AutoSize di 
questi controlli a false. 

• Evitare l'uso esplicito delle coordinate in pixel, come quando si disegna 
direttamente su un canvas. Modificare, invece, le coordinate per un rapporto 
proporzionato alia differenza delle risoluzioni degli schermi tra il computer di 
sviluppo e il computer dell'utente. Per esempio, se l'applicazione disegna su un 
canvas un rettangolo alto dieci pixel e largo venti, basta moltiplicare tali numeri 
per il rapporto della differenza delle risoluzioni degli schermi. Questa operazione 
garantisce che il rettangolo apparira con le stesse dimensioni con risoluzioni dello 
schermo differenti. 

Regolazione in funzione del numero di colori disponibili 

Se si vuole tenere conto del fatto che tutti i computer di distribuzione non sono 
configurati con la stessa disponibilita di colori, il modo piu sicuro per aver buoni 
risultati e quello di usare grafici con il minimo numero possibile di colori. Cio e 
particolarmente vero per i glifi dei controlli, che normalmente usano della grafica a 
16 colori. Per la visualizzazione delle figure, o vengono diverse fornite copie delle 
immagini con risoluzioni e intensita di colore differenti, oppure vengono indicati i 
requisiti minimi di risoluzione e di colore per l'applicazione. 

Font 



Windows viene distribuito con un set standard di font TrueType e vettoriali. Linux 
viene distribuito con un set standard di font, che variano a seconda della 
distribuzione. Quando si progetta un'applicazione che deve essere distribuita su altri 
computer, bisogna tener conto del fatto che non tutti i computer potrebbero avere 
altri font oltre a quelli del set standard. 

Tutti i componenti di testo usati nell'applicazione devono usare i font che sono 
probabilmente disponibili su tutti i computer di distribuzione. 

Quando in un'applicazione e assolutamente necessario usare un font non standard, 
occorre distribuire tale font con l'applicazione. Oppure, si deve fare in modo che il 
programma di installazione o l'applicazione stessa installino il font sul computer di 
distribuzione. La distribuzione dei font di produttori terzi puo essere soggetta a 
limitazioni imposte da chi ha creato il font. 

Windows prevede una misura di sicurezza che consente di usare un font che sul 
computer non esiste. Lo sostituisce con un altro font esistente che ritiene essere 
quello piu simile. Anche se e vero che cio puo impedire l'insorgere di errori relativi 
alia mancanza di font, il risultato finale puo essere un degrado dell'aspetto visuale 
dell'applicazione. E meglio prepararsi a questa eventualita in fase di progettazione. 

Per rendere disponibile in un'applicazione Windows un font non standard, usare le 
funzioni API di Windows AddFontResource e DeleteFontResource. Distribuire il file iot 
del font non standard con l'applicazione. 
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per la licenza d'uso del software 



Versioni del sistema operativo 



Quando si usano API del sistema operativo o si accede dall'applicazione ad aree del 
sistema operativo, c'e la possibility che la funzione, l'operazione o l'area non siano 
disponibili su computer con versioni diverse del sistema operativo. 

Per tener conto di questa possibility, sono disponibili alcune opzioni: 

• Specificare nei requisiti di sistema dell'applicazione le versioni del sistema 
operativo su cui il programma puo funzionare. La responsabilita di installare e di 
utilizzare l'applicazione solo su versioni di sistema operativo compatibili e a 
carico dell'utente. 

• Controllare la versione del sistema operativo mentre si installa l'applicazione. Se e 
presente una versione di sistema operativo non compatibile, si deve interrompere 
la procedura di installazione o quanto meno informare l'utente del problema. 

• Controllare in esecuzione la versione del sistema operativo, immediatamente 
prima di eseguire un'operazione non valida per tutte le versioni. Se e presente una 
versione di sistema operativo non compatibile, annullare la procedura e notificarlo 
all'utente. In alternativa, includere sezioni di codice differente da eseguire a 
seconda della versione del sistema operativo. 

Alcune operazioni vengono eseguite in Windows 95/98 in modo differente 
rispetto a Windows NT/2000/XP. Per determinare la versione in uso di Windows, 
ricorrere alia funzione API di Windows GetVersionEx. 



La distribuzione di alcuni file associati alle applicazioni C++Builder e soggetta a 
limitazioni o non e affatto consentita. I documenti seguenti descrivono gli aspetti 
legali relativi alia distribuzione di questi file: 

• DEPLOY 

• README 

• Accordo di licenza 

• Documentazione sui prodotti di terze parti 



II documento DEPLOY tratta alcuni aspetti legali connessi alia distribuzione dei 
diversi componenti, dei programmi di utilita e di altre aree del prodotto che possono 
far parte o essere associati a un'applicazione C++Builder. II documento DEPLOY e 
installato nella directory principale di C++Builder. Gli argomenti trattati 
comprendono, tra l'altro 

• .exe, .dll, e .bpl files 

• I componenti e i package di progettazione 



Requisiti 



per la licenza d'uso del software 



DEPLOY 
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• Borland Database Engine (BDE) 

• I controlli ActiveX 

• Immagini di esempio 

• SQL Links 

README 



II documento README contiene le informazioni dell'ultimo minuto su C++Builder, 
oltre a informazioni che potrebbero influenzare i diritti di ridistribuzione dei 
componenti, dei programmi di utilita o di altre aree del prodotto. II documento 
README e installato nella directory principale di C++Builder. 

Accordo di licenza 



L'accordo di licenza di C++Builder, un documento stampato, tratta gli altri diritti 
legali e gli obblighi riguardanti C++Builder. 

Documentazione sui prodotti di terze parti 



I diritti di ridistribuzione per i componenti, i programmi di utilita, le applicazioni 
aggiuntive, i motori di database e gli altri prodotti di terzi parti sono stabiliti 
dall'organismo che fornisce il prodotto. Per informazioni riguardanti la 
ridistribuzione di tali prodotti con le applicazioni C++Builder, consultare la 
documentazione relativa al prodotto o al produttore prima di effettuarne la 
distribuzione. 
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Sviluppo di applicazioni database 

I capitoli inclusi nella sezione "Sviluppo di applicazioni database" presentano i 
concetti e le tecniche necessarie per creare applicazioni database in C++Builder. 

II livello di supporto per la costruzione di applicazioni database varia a seconda della 
versione di C++Builder acquistata. In particolare, si deve essere in possesso almeno 
dell'edizione Professional per utilizzare dataset client e della versione Enterprise per 
sviluppare applicazioni database multi-tier. 



Sviluppo di applicazioni database 



Capitolo 




Progettazione di applicazioni 

database 

Le applicazioni database consentono agli utenti di interagire con le informazioni 
memorizzate nei database. Questi forniscono la struttura per le informazioni, e ne 
consentono la condivisione tra applicazioni differenti. 

C++Builder fornisce il supporto per le applicazioni database relazionali. I database 
relazionali organizzano le informazioni in tabelle, che contengono righe (record) e 
colonne (campi). Queste tabelle possono essere manipolate attraverso semplici 
operazioni, note come calcoli relazionali. 

Nella progettazione di un'applicazione database occorre capire come sono strutturati 
i dati. In base alia struttura e possibile, quindi, progettare un'interfaccia per 
visualizzare i dati all'utente e consentirgli di immettere nuove informazioni o di 
modificare i dati esistenti. 

In questo capitolo vengono riportate alcune considerazioni di carattere generale per 
la progettazione di un'applicazione database e vengono analizzate le decisioni da 
adottare per la definizione di un'interfaccia utente. 

Uso dei databases 



C++Builder include molti componenti per accedere ai database e rappresentare le 
informazioni in essi contenute. Essi sono raggruppati il base al meccanismo di 
accesso di dati: 

• La pagina BDE della Component palette contiene i componenti che utilizzano 
Borland Database Engine (BDE). Borland Database Engine (BDE) definisce una 
vasta API per l'interazione con i database. Fra tutti i meccanismi per l'accesso ai 
dati, BDE e quello che supporta la piu vasta gamma di funzioni e dispone del 
maggior numero di programmi di utilita di supporto. E senza dubbio il miglior 
modo per operare con dati in tabelle Paradox o dBASE. Tuttavia, e anche il 
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meccanismo piu complicato da distribuire. Per ulteriori informazioni sull'uso dei 
componenti BDE, consultare il Capitolo 24, "Uso di Borland Database Engine". 

• La pagina ADO della Componet palette contiene componenti che utilizzano 
ActiveX Data Objects (ADO) per accedere tramite OLEDB alle informazioni nel 
database. ADO e uno standard di Microsoft. Esiste una vasta gamma di driver 
ADO disponibili per il collegamento a vari server di database. L'utilizzo di 
componenti basati su ADO permette di integrare l'applicazione in un ambiente 
basato su ADO (ad esempio, che utilizza application server basati su ADO). Per 
ulteriori informazioni sull'uso dei componenti ADO, consultare il Capitolo 25, 
"Operazioni con componenti ADO". 

• La pagina dbExpress della Componet palette contiene componenti che utilizzano 
dbExpress per accedere alle informazioni nel database. dbExpress e un gruppo di 
driver leggeri che consentono un accesso rapido alle informazioni dei database. 
Inoltre, i componenti dbExpress supportano lo sviluppo multipiattaforma perche 
sono disponibili anche in ambiente Linux. Tuttavia, i componenti database 
dbExpress supportano anche una gamma molto ristretta di funzioni per la 
manipolazione dei dati. Per ulteriori informazioni sull'uso dei componenti 
dbExpress, consultare il Capitolo 26, "Uso di dataset unidirezionali". 

• La pagina InterBase della Component palette contiene componenti che accedono a 
database InterBase in modo diretto, senza passare attraverso uno strato di motore 
separate 

• La pagina Data Access della Component palette contiene componenti che possono 
essere utilizzati con qualsiasi meccanismo di accesso ai dati. Questa pagina 
include TClientDataset, che puo funzionare con dati memorizzati su disco oppure, 
utilizzando il componente TDataSetProvider, anch'esso su questa pagina, con 
componenti di uno degli altri gruppi. Per ulteriori informazioni sull'uso dei 
dataset client, consultare il Capitolo 27, "Utilizzo dei dataset client", per ulteriori 
information su TDataSetProvider, vedere il Capitolo 28, "Uso di componenti 
provider". 

Le varie versioni di C++Builder includono driver differenti per l'accesso a server di 
database utilizzando BDE, ADO o dbExpress. 

Nella progettazione di un'applicazione database occorre decidere quale set di 
componenti utilizzare. Ogni meccanismo di accesso di dati e differente per la gamma 
di funzioni disponibili, per la semplicita di distribuzione e per la disponibilita di 
driver per supportare vari server di database. 

Oltre a scegliere un meccanismo di accesso ai dati, e necessario scegliere un server di 
database. Esistono vari tipi di database e sara opportuno soppesare i vantaggi e gli 
svantaggi di ognuno prima di scegliere un particolare server di database. 

Tutti i tipi di database contengono tabelle che memorizzano le informazioni. Inoltre, 
la maggior parte dei server (ma non tutti) supportano funzioni aggiuntive come 

• Sicurezza del database 

• Transazioni 

• Integrita referenziale, procedure registrate e trigger 
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Tipi di database 



I server di database relazionali agiscono in modo differente a seconda del modo 
utilizzato per memorizzare le informazioni e a seconda del modo utilizzato per 
permettere a piu utenti di accedere contemporaneamente a quelle informazioni. 
C++Builder fornisce il supporto per due tipi di server database relazionale: 

• I server di database remoti di solito risiedono in una macchina separata. A volte, i 
dati provenienti da un server di database remoto non risiedere nemmeno in una 
singola macchina, ma sono distribuiti su numerosi server. Benche i server di 
database remoti si differenzino a seconda del modo utilizzato per memorizzare le 
informazioni, essi presentano ai client un'interfaccia logica comune. Questa 
interfaccia comune e SQL (Structured Query Language).Poiche si accede ad essi 
utilizzando il linguaggio SQL, a volte vengono anche chiamati server SQL. (Un 
altro nome utilizzato e Remote Database Management system o RDBMS.) Oltre ai 
comuni comandi che compongono il linguaggio SQL, la maggior parte dei server 
di database remoti supporta un "dialetto" univoco di SQL. Esempi di server SQL 
sono InterBase, Oracle, Sybase, Informix, Microsoft SQL server e DB2. 

• I database locali risiedono nell'unita locale o in una rete locale. Essi possiedono 
API proprietarie per accedere ai dati. Quando sono condivisi da piu utenti, usano 
meccanismi di bloccaggio basati su file di database. A causa di cio, a volte vengono 
chiamati database basati su file. Esempi di database locali sono Paradox, dBASE, 
FoxPro e Access. 

Le applicazioni che usano i database locali sono chiamate applicazioni single-tier 
perche l'applicazione e il database condividono un singolo file system. Le 
applicazioni che utilizzano i server di database remoti sono definite applicazioni 
two-tier o applicazioni multi-tier perche l'applicazione e il database operano su 
sistemi (o tier) indipendenti). 

La scelta del tipo di database da utilizzare dipende da numerosi fattori. Ad esempio, 
i dati possono essere gia memorizzati in un database esistente. Se si creano le tabelle 
di database che saranno utilizzate dall'applicazione, sara bene porsi le seguenti 
domande: 

• Quanti utenti condivideranno queste tabelle? I server di database remoti sono 
progettati perche numerosi utenti possano accedervi contemporaneamente. Essi 
forniscono il supporto per piu utenti attraverso un meccanismo chiamato 
transazioni. Anche alcuni database locali (come Local InterBase) forniscono il 
supporto per le transazione, mentre la maggior parte fornisce solo meccanismi 
basati sul blocco dei file e alcuni (come file dei dataset client) non forniscono 
affatto alcun supporto multiutente. 

• Quanti dati conterranno le tabelle? I server di database remoti possono contenere 
molti piu dati dei database locali. Alcuni server di database remoti sono progettati 
per immagazzinare grandi quantita di dati mentre altri sono ottimizzati per altri 
criteri (come gli aggiornamenti veloci). 

• Quale tipo di prestazioni (velocita) si richiedono al database? Di solito i database 
locali sono piu rapidi dei server di database remoti perche risiedono nello stesso 
sistema dell'applicazione database. Server di database remoti differenti sono 
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ottimizzati per supportare tipi di operazioni differenti, pertanto, quando si sceglie 
un server di database remoto, e bene prestare attenzione alle prestazioni. 

• Quale tipo di supporto sara disponibile per la gestione del database? I database 
locali richiedono meno supporto dei server di database remoti. Di solito, sono 
anche meno costosi da far funzionare perche non richiedono server installati 
separatamente o costose licenze d'uso per ogni installazione. 

Sicurezza del database 



Spesso i database contengono informazioni riservate. Diversi database forniscono 
piani di sicurezza per la protezione di queste informazioni. Alcuni, come Paradox e 
dBASE, forniscono solo sicurezza a livello di tabella o di campo. Quando gli utenti 
cercano di accedere alle tabelle protette, viene loro richiesto di fornire una password. 
Una volta che sono stati identificati, gli utenti possono visualizzare solo i campi (o le 
colonne) ai quali hanno l'accesso. 

Molti server SQL richiedono, per poter essere usati, almeno una password e un nome 
utente. Dopo che l'utente ha effettuato il login al database, il suo nome e la sua 
password determinano quali tabelle possono essere usate. Per informazioni su come 
fornire le password ai server SQL, consultare "Controllo del login al server" a 
pagina 21-4. 

Quando si progettano applicazioni database, occorre tener conto del tipo di autentica 
richiesta dal database server. Spesso, le applicazioni sono progettate per nascondere 
agli utenti il login esplicito al database, e richiedono che l'utente effettui solo il login 
all'applicazione. Se non si vuole che gli utenti siano obbligati a fornire una password, 
occorre usare un database che non la richiede o fornire la password e il nome utente 
al server da programma. In questo secondo caso si deve prestare attenzione al rischio 
di aprire una breccia nella sicurezza leggendo la password dall'applicazione. 

Se si richiede all'utente di fornire una password, occorre tener conto del momento in 
cui questa viene richiesta. Se si sta utilizando un database locale ma si prevede in 
seguito di passare a un server SQL piu grande, potrebbe essere opportuno richiedere 
la password nel momento in cui si effettua il login al database SQL invece che 
all'apertura delle singole tabelle. 

Se l'applicazione richiede piu password perche occorre effettuare il login a diversi 
sistemi o database protetti, si potrebbe prevedere che gli utenti forniscono un'unica 
password principale da utilizzare per accedere a una tabella contenente tutte le 
password richieste dai sistemi protetti. L'applicazione fornisce, quindi, le password 
da programma, senza richiedere all'utente di fornirne altre. 

Nelle applicazioni multi-tier puo essere opportuno usare un modello di sicurezza 
completamente diverse Si puo usare HTTP o COM per controllare l'accesso ai tier 
intermedi, e lasciare che siano essi a gestire tutti i dettagli del login ai database 
server. 
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Transazioni 



Una transazione e un gruppo di azioni che devono essere tutte portate a termine con 
successo su una o piu tabelle di un database prima che vengano inoltrate (rese 
permanenti). Se una delle azioni del gruppo non riesce, tutte le azioni vengono 
respinte (annullate). 

Le transazioni assicurano che 

• Tutti gli aggiornamenti di una singola transazione saranno effettuati oppure 
annullati e riportati al loro stato precedente. Questo comportamento viene definito 
atomicita. 

• Una transazione e una trasformazione corretta dello stato di sistema, che preserva 
gli invarianti di stato. Questo comportamento viene definito congruenza. 

• Le transazioni simultanee non vedono i rispettivi risultati parziali o non 
completati, che potrebbero creare inconsistenze nello stato di applicazione. Questo 
comportamento viene definito isolamento. 

• Gli aggiornamenti sottoposti ai record sopravvivono ai malfunzionamenti, 
compresi i malfunzionamenti dovuti a problemi di comunicazione, di processo e 
del sistema server. Questo comportamento viene definito resistenza. 

Le transazioni proteggono dai guasti all'hardware che si verificano nel mezzo di un 
comando o di un set di comandi del database. La registrazione transazionale 
consente di recuperare lo stato resistente dopo un malfunzionamento dei supporti di 
memorizzazione su disco. Le transazioni costituiscono anche la base del controllo di 
simultaneity multiutente sui server SQL. Quando un utente interagisce con il 
database solo tramite le transazioni, i suoi comandi non possono rompere l'unita 
della transazione di un altro utente. Invece, il server SQL programma le transazioni 
in arrivo, che hanno successo o falliscono globalmente. 

II supporto delle transazioni non e incluso nella maggior parte dei database locali, 
anche se e previsto da Local InterBase. Inoltre, i driver BDE forniscono un supporto 
transazionale limitato per alcuni database locali. II supporto delle transazioni sul 
database viene fornito dal componente che rappresenta la connessione al database. 
Per dettagli sulla gestione delle transazioni utilizzando un componente database 
connection, vedere "Gestione delle transazioni" a pagina 21-6. 

Nelle applicazioni multi-tiered e possibile creare transazioni che includono azioni 
diverse dalle operazioni del database o che riguardano piu database. Per 
informazioni dettagliate sull'uso delle transazioni nelle applicazioni multi-tiered, 
consultare "Gestione delle transazioni nelle applicazioni multi-tiered" a 
pagina 29-18. 

Integrita referenziale, procedure registrate e trigger 



Tutti i database relazionali hanno alcune caratteristiche comuni che consentono alle 
applicazioni di memorizzare e di manipolare i dati. Inoltre, spesso i database 
forniscono altre caratteristiche specifiche, che possono risultare utili per garantire 
relazioni coerenti tra le tabelle di un database. Ne fanno parte 
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• Integrita referenziale. L'integrita referenziale fornisce un meccanismo per 
impedire che le relazioni master /detail tra le tabelle vengano danneggiate. 
Quando l'utente cerca di cancellare un campo di una tabella master, il che 
genererebbe record detail orfani, le regole dell'integrita referenziale impediscono 
la cancellazione o cancellano automaticamente i record detail orfani. 

• Procedure registrate. Le procedure registrate sono set di istruzioni SQL a cui viene 
assegnato un nome e che vengono memorizzate su un server SQL. Di solito, queste 
procedure eseguono sul server normali operazioni relative ai database, e 
restituiscono set di record (dataset). 

• Trigger. I trigger sono set di istruzioni SQL che vengono eseguiti 
automaticamente in risposta a un particolare comando. 

Architettura di un database 



Le applicazioni database sono costituite dagli elementi dell'interfaccia utente, dai 
componenti che rappresentano i dati contenuti dalle tabelle in quei database 
(dataset). II modo di organizzare queste parti genera l'architettura dell'applicazione 
database. 

Struttura generate 



Benche esistano molti modi differenti per organizzare i componenti in 
un'applicazione database, la maggior parte segue lo schema generale illustrato nella 
Figura 18.1: 

Figura 18.1 Architettura generale di un database 



Data module 




La scheda dell'interfaccia utente 

E buona norma isolare l'interfaccia utente su una scheda che sia completamente 
separata dal resto dell'applicazione. Questo comporta numerosi vantaggi. Isolando 
l'interfaccia utente dai componenti che rappresentano le informazioni di database, si 
introduce una maggior flessibilita nel proprio progetto. Le modifiche al modo in cui 
vengono gestite le informazioni di database non comporteranno la riscrittura 
dell'interfaccia utente e le modifiche all'interfaccia utente non comporteranno la 
modifica di quelle parti dell'applicazione che operano sul database. Inoltre, questo 
tipo di isolamento permette di sviluppare schede comuni che e possibile condividere 
tra piu applicazioni, fornendo cosi un'interfaccia utente coerente. Memorizzando 
collegamenti a schede ben progettate nell'Object Repository, qualunque sviluppatore 
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puo basarsi su blocchi fondamentali gia esistenti anziche iniziare ex novo ogni nuovo 
progetto. La condivisione di schede rende anche possibile sviluppare standard 
aziendali per le interfacce delle applicazioni. Per ulteriori informazioni sulla 
creazione dell'interfaccia utente di un'applicazione database, consultare 
"Progettazione dell'interfaccia utente" a pagina 18-16. 

II modulo dati 

Se l'interfaccia utente e stata isolata in schede indipendenti, e possibile utilizzare un 
modulo dati per alloggiare i componenti che rappresentano le informazioni di 
database (dataset) e i componenti che connettono questi dataset alle altre parti 
dell'applicazione. Analogamente alle schede dell'interfaccia utente, e possibile 
condividere i moduli dati nell'Object Repository in modo che possano essere 
riutilizzati o condivisi tra le applicazioni. 

II datasource 

II primo elemento nel modulo dati e un datasource. II datasource agisce come un 
condotto tra l'interfaccia utente e un dataset che rappresenta le informazioni 
contenute in un database. Numerosi controlli data-aware su una scheda possono 
condividere un singolo datasource, nel quale caso cio che viene visualizzato in ogni 
controllo e sincronizzato in modo che, man mano che l'utente fa scorrere i record, in 
ogni controllo viene visualizzato il valore corrispondente presente nei campi del 
record corrente. 

II dataset 

II cuore dell'applicazione database e il dataset. Questo componente rappresenta un 
insieme di record provenienti dal database sottostante. Questi record possono essere 
i dati di una singola tabella di database, un sottoinsieme dei campi o dei record in 
una tabella oppure informazioni provenienti da piu tabelle unite in una singola vista. 
Grazie all'utilizzo dei dataset, la logica dell'applicazione e esentata dalla necessita di 
ristrutturare le tabelle fisiche nei database. Nel caso si cambi il database sottostante, 
potrebbe essere necessario modificare il modo in cui il componente dataset specifica i 
dati che contiene, ma il resto dell'applicazione potrebbe continuare a funzionare 
senza modifiche. Per ulteriori informazioni sulle proprieta e sui metodi comuni dei 
dataset, consultare il Capitolo 22, "I dataset". 

La connessione ai dati 

I diversi tipi di dataset utilizzano meccanismi differenti per il collegamento alle 
informazioni del database sottostante. Questi meccanismi differenti, a loro volta, 
sono quelli che comportano le principali differenze neU'architettura delle 
applicazioni database che e possibile costruire. Esistono quattro meccanismi di base 
per il collegamento ai dati: 

• Connessione diretta a un server di database. La maggior parte dei dataset utilizza 
un discendente di TCustomConnection per rappresentare la connessione a un server 
di database. 

• Utilizzo di un file dedicato su disco. I dataset client supportano la capacita di 
operare con un file dedicato su disco. Quando si opera con un file dedicato non e 
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necessario alcun componente connection separato perche lo stesso dataset client sa 
come leggere dal file e scrivere in esso. 

• Collegamento a un altro dataset. I dataset client possono operare con dati forniti 
da un altro dataset. Un componente TDataSetProvider agisce da intermediario tra il 
dataset client e il proprio dataset sorgente. Questo provider di dataset puo 
risiedere nello stesso modulo dati del dataset client o puo fare parte di un 
application server in esecuzione su un'altra macchina. Se il provider fa parte di un 
application server, e necessario anche un discendente speciale di 

T Custom-Connection per rappresentare la connessione all'application server. 

• Ottenimento dei dati da un oggetto RDS DataSpace. I dataset ADO possono 
utilizzare un componente TRDSConnection per smistare i dati nelle applicazioni 
database multi-tier costruite utilizzando application server basati su ADO. 

Talvolta, questi meccanismi possono essere combinati in una singola applicazione. 



Connessione diretta a un server di database 



L'architettura di database piu comune e quella in cui il dataset utilizza un 
componente connection per stabilire una connessione con un server di database. II 
dataset quindi preleva i dati direttamente dal server e invia le modifiche 
direttamente al server. L'architettura e illustrata nella Figura 18.2. 

Figura 18.2 Connessione diretta a un server di database 
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Ogni tipo di dataset utilizza il proprio tipo di componente connection, che 
rappresenta un singolo meccanismo di accesso ai dati: 

• Se il dataset e un dataset BDE come TTable, TQuery o TStoredProc, il componente 
connection e un oggetto TDataBase. Si collega il dataset al componente database 
impostandone la proprieta Database. Non e necessario aggiungere esplicitamente 
un componente databse quando si usa un dataset BDE. Se si imposta la proprieta 
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DatabaseName del dataset, in fase di esecuzione viene creato automaticamente un 
componente database. 

• Se il dataset e un dataset ADO come TADODataSet, TADOTable, TADOQuery o 
TADOStoredProc, il componente connection e un oggetto TADOConnection. Si 
collega il dataset al componente connection ADO impostandone la proprieta 
ADOConnection. Come con i dataset BDE, non e necessario aggiungere 
esplicitamente il componente connection: e possibile invece impostare la proprieta 
ConnectionString del dataset. 

• Se il dataset e un dataset dbExpress come TSQLDataSet, TSQLTable, TSQLQuery o 
TSQLStoredProc, il componente connection e un oggetto TSQLConnection. Si 
collega il dataset al componente connection SQL impostandone la proprieta 
SQLConnection. Quando si utilizzano dataset dbExpress, e necessario aggiungere 
esplicitamente il componente connection. Un'altra differenza fra il dataset 
dbExpress e gli altri dataset e che i dataset dbExpress sono sempre a sola lettura e 
unidirezionali: cio significa che e possibile spostarsi fra i record solo in base alia 
loro sequenza e non e possibile utilizzare i metodi del dataset che supportano le 
modifiche. 

• Se il dataset e un dataset InterBase Express come TIBDataSet, TIBTable, TIBQuery o 
TIBStoredProc, il componente connection e un oggetto TIBDatabase. Si collega il 
dataset al componente di database IB impostandone la proprieta Database. Come 
con i dataset dbExpress, e necessario aggiungere esplicitamente il componente 
connection. 

Oltre ai componenti elencati sopra, e possibile utilizzare un dataset client 
specializzato come TBDEClientDataSet, TSQLClientDataSet o TIBCHentDataSet con un 
componente database connection. Se si utilizza uno di questi dataset client, 
specificare il tipo appropriato di componente connection come valore della proprieta 
DBConnection. 

Benche ogni tipo di dataset utilizzi un componente connection diverso, tutti quanti 
svolgono la maggior parte delle stesse attivita e rendono disponibili molte proprieta, 
metodi e eventi che tutti hanno in comune. Per ulteriori informazioni sulle 
similitudini tra i diversi componenti di connessione ai database, vedere il Capitolo 
21, "Connessione ai database". 

Questa architettura rappresenta sia un'applicazione single-tier sia un'applicazione 
two-tier, a seconda che il server di database sia un database locale o un server di 
database remoto. La logica che tratta le informazioni di database e nella stessa 
applicazione che implementa l'interfaccia utente, sebbene isolata in un modulo dati. 

I componenti connection o i driver necessari per creare applicazioni two-tier non 
sono disponibili in tutte le versione di C++Builder. 

Utilizzo di un file dedicate su disco 



La forma piu semplice di un'applicazione database che e possibile scrivere non 
utilizza affatto un server di database. Invece, con MyBase, utilizza la capacita dei 
dataset client di salvare il proprio contenuto in un file e di caricare i dati da un file. 
Questa architettura e illustrato nella Figura 18.3: 
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Figura 18.3 Un'applicazione database basata su file 
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Se si utilizza questo approccio basato su file, l'applicazione scrive le modifiche sul 
disco utilizzando il metodo SaveToFile del dataset client. SaveToFile richiede un 
parametro, il nome del file da creare (o da sovrascrivere) che contiene la tabella. 
Quando si vuole leggere una tabella precedentemente scritta utilizzando il metodo 
SaveToFile, utilizzare il metodo LoadFromFile. Anche LoadFromFile richiede un 
parametro, il nome del file che contiene la tabella. 

Se si caricano i dati e li si salva utilizzando sempre lo stesso file, e possibile utilizzare 
la proprieta FileName invece dei metodi SaveToFile e LoadFromFile. Quando FileName e 
impostata a un nome di file valido, i dati vengono automaticamente caricati dal file 
quando si apre il dataset client e salvati sul file quando si chiude il dataset client. 

Questa semplice architettura basata su file e un'applicazione single-tier. La logica che 
tratta le informazioni di database e nella stessa applicazione che implementa 
l'interfaccia utente, sebbene isolata in un modulo dati. 

L'approccio basato su file ha il vantaggio della semplicita. Non occorre installare, 
configurare o distribuire alcun server di database, (anche se il dataset client necessita 
di midas.dll). Non c'e alcuna necessita di licenze di postazione o di gestione del 
database. 

Inoltre, alcune versioni di C++Builder permettono di convertire documenti arbitrari 
XML in pacchetti dati utilizzati da un dataset client. Pertanto, l'approccio basato su 
file pud essere utilizzato per operare con documenti XML oltre che con dataset 
dedicati. Per informazioni sulla conversione tra documenti XML e pacchetti dati di 
dataset client, vedere il Capitolo 30, "Uso di XML nelle applicazioni database". 

L'approccio basato su file non offre alcun supporto per piu utenti. II dataset deve 
essere dedicato completamente all'applicazione. I dati vengono salvati in un file su 
disco e caricati in un momento successivo, ma non c'e alcuna protezione nativa atta 
ad impedire a piu utenti di sovrascrivere l'un l'altro gli archivi dati. 

Per ulteriori informazioni sull'utilizzo di un dataset client con dati memorizzati su 
disco, vedere "Uso di un dataset client con dati basati su file" a pagina 27-35. 



Collegamento a un altro dataset 



Esistono dataset client specializzati che utilizzano BDE o dbExpress per collegarsi a un 
server di database. Questi dataset client specializzati sono, infatti, componenti 
compositi che dispongono di un altro dataset interno per accedere ai dati e di un 
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componente provider interno per assemblare i dati dal dataset sorgente e riapplicare 
gli aggiornamenti al server di database. Questi componenti compositi risultano un 
po' piu pesanti in termini di gestione, ma offrono alcuni vantaggi: 

• I dataset client rappresentano il modo piu affidabile per operare con gli 
aggiornamenti in cache. Per impostazione predefinita, altri tipi di dataset inviano 
le modifiche direttamente al server di database. Utilizzando un dataset che 
memorizza gli aggiornamenti nella cache locale e li applica tutti in un secondo 
momento con una singola transazione e possibile ridurre il traffico di rete. Per 
informazioni sui vantaggi derivanti dall'utilizzo di dataset client per memorizzare 
gli aggiornamenti in cache, vedere "Utilizzo di un dataset client per registrare in 
cache gli aggiornamenti" a pagina 27-17. 

• I dataset client possono applicare le modifiche direttamente a un server di 
database se il dataset e a sola lettura. Se si utilizza dbExpress, questo e l'unico modo 
per modificare i dati nel dataset (ed e anche l'unico modo per spostarsi 
liberamente tra i dati). Anche se non si utilizza dbExpress, i risultati di alcune query 
e di tutte le procedure registrate sono a sola lettura. L'utilizzo di un dataset client 
fornisce un metodo standard per rendere modificabili tali dati. 

• Poiche i dataset client possono operare direttamente con file dedicati su disco, 
l'utilizzo di un dataset client pud essere combinato con un modello basato su file 
in modo da ottenere un'applicazione "briefcase " flessibile. Per informazioni sul 
modello briefcase, vedere "Combinazione dei vari approcci" a pagina 18-15. 

Oltre a questi dataset client specializzati, esiste un dataset client generico 
(TClientDataSet), che non dispone di un dataset interno e di un provider di dataset. 
Benche TClientDataSet non abbia alcun meccanismo interno per l'accesso ai database, 
e possibile connetterlo a un altro dataset esterno da cui preleva i dati e a cui invia gli 
aggiornamenti. Benche questo approccio sia un po' piu complicato, a volte potrebbe 
essere quello migliore: 

• Poiche il dataset sorgente e il provider di dataset sono esterni, si ha un maggior 
controllo sul modo in cui prelevano i dati e applicano gli aggiornamenti. Ad 
esempio, il componente provider rende disponibili molti eventi che non sono 
disponibili se si utilizza un dataset client specializzato per accedere ai dati. 

• Se il dataset sorgente e esterno, e possibile collegarlo mediante una relazione 
master/detail con un altro dataset. Un provider esterno converte 
automaticamente questa configurazione in un singolo dataset con dettagli 
annidati.Se il dataset sorgente e interno, e impossibile creare set di dettaglio 
annidati secondo questa modalita. 

• La connessione di un dataset client a un dataset esterno e un'architettura che puo 
essere estesa progressivamente fino a piu tier. Poiche il processo di sviluppo puo 
diventare sempre piu complesso e costoso man mano che aumenta il numero di 
tier, potrebbe essere opportuno iniziare a sviluppare l'applicazione come single- 
tier o two-tier. Via via che la quantita di dati, il numero di utenti e il numero di 
applicazioni differenti che accedono ai dati cresce, si puo passare gradualmente a 
un'architettura multi-tiered. Se si presume che si arrivera a utilizzare 
un'architettura multi-tier, puo riconvenienete iniziare lo sviluppo utilizzando un 
dataset client e un dataset sorgente esterno. In questo modo, quando si spostera 
l'accesso ai dati e la logica di gestione su un tier intermedio, l'investimento fatto in 
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termini di sviluppo risuleta protetto poiche il codice potra essere riutilizzato man 
mano che l'applicazione cresce. 

• TCHentDataSet puo collegarsi a qualsiasi dataset sorgente. Cio significa che e 
possibile utilizzare dataset custom (componenti forniti da terze parti) per i quali 
non esiste alcun dataset client specializzato corrispondente. Alcune versioni di 
C++Builder includono anche componenti provider particolari che connettono un 
dataset client a un documento XML invece che a un altro dataset. II funzionamento 
e analogo alia connessione di un dataset client a un altro dataset (sorgente), salvo 
che il provider XML utilizza un documento XML al posto di un dataset. Per 
informazioni su questi provider XML, vedere "Impiego di un documento XML 
come origine di un provider" a pagina 30-8.) 

Esistono due versioni dell'architettura che connette un dataset client a un dataset 
esterno: 

• Connessione di un dataset client a un altro dataset nella stessa applicazione. 

• Utilizzo di un' architettura multi-tier. 



Connessione di un dataset client a un altro dataset nella stessa applicazione 

Utilizzando un componente provider, e possibile connettere TCHentDataSet a un altro 
dataset (sorgente). II provider assembla le informazioni del database in pacchetti dati 
trasportabili (che possono essere utilizzati dai dataset client) e applica gli 
aggiornamenti ricevuti in pacchetti delta (creati dai dataset client) a un server di 
database. Questa architettura e illustrata nella Figura 18.4. 

Figura 18.4 Architettura che combina un dataset client e un altro dataset 



Client application 



Data module 



Data source 



< > 



Client dataset 



Connection 
component 




Dataset 



< — >■ Provider 



18-12 Guida alia programmazione 



Architettura di un database 



Questa architettura rappresenta sia un'applicazione single-tier sia un'applicazione 
two-tier, a seconda che il server di database sia un database locale o un server di 
database remoto. La logica che tratta le informazioni di database e nella stessa 
applicazione che implementa l'interfaccia utente, sebbene isolata in un modulo dati. 

Per collegare il dataset client con il provider, impostarne la proprieta ProviderName al 
nome del componente provider. II provider deve essere nello stesso modulo dati del 
dataset client. Per collegare il provider con il dataset sorgente, impostarne la 
proprieta DataSet. 

Una volta che il dataset client e collegato con il provider e il provider e collegato con 
il dataset sorgente, questi componenti gestiscono automaticamente tutti i dettagli 
necessari per prelevare, visualizzare e consentire lo spostamento attraverso i record 
del database (partendo dall'assunto che dataset sorgente sia connesso a un database). 
Per applicare al database le modifiche apportate dall'utente, e necessario solo 
chiamare il metodo Applyllpdates del dataset client. 

Per ulteriori informazioni sull'utilizzo di un dataset client con un provider, vedere 
"Uso di un dataset client con un provider di dati" a pagina 27-26. 

Utilizzo di un'architettura multi-tier 

Quando le informazioni del database comprendono relazioni complesse tra piu 
tabelle, o quando il numero di client aumenta, potrebbe essere necessario usare 
un'applicazione multi-tier. Le applicazioni multi-tier hanno tier intermedi fra 
l'applicazione client e il server di database. Questa architettura e illustrata nella 
Figura 18.5. 
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Figura 18.5 Architettura multi-tier di un database 
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La figura precedente rappresenta un'applicazione three-tier .La logica che tratta le 
informazioni di database esuun sistema, o tier, separata. Questo tier intermedio 
centralizza la logica che governa le interazioni col database centralizzando in tal 
modo il controllo sulle relazioni tra i dati. Cio permette a varie applicazioni client di 
utilizzare gli stessi dati, assicurando al contempo la congruenza della logica dei dati. 
Permette anche di ottenere applicazioni client piu piccole perche gran parte 
dell'elaborazione e demandata al tier intermedio. Queste applicazioni client piu 
piccole risultano piu facili da installare, configurare e gestire. Le applicazioni multi- 
tier possono anche migliorare le prestazioni distribuendo le attivita di elaborazione 
dei dati su parecchi sistemi. 

L'architettura multi-tier e molto simile al modello precedente. Si differenzia 
principalmente per il fatto che il dataset sorgente, che si collega al server di database, 
e il provider, che agisce come intermediario tra quel dataset sorgente e il dataset 
client, sono stati spostati entrambi in un'applicazione separata. Questa e applicazione 
separata e detta application server (o talvolta "data broker remoto"). 

Poiche il provider e stato spostato in un'applicazione separata, il dataset client non 
puo piu essere collegato al dataset sorgente impostando semplicemente la sua 
proprieta ProviderName. Inoltre, deve utilizzare alcuni tipi di componente connection 
per individuare e connettersi all'applicazione server. 
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Esistono molti tipi di componenti connection in grado di connettere un dataset client 
a un application server. Sono tutti discendenti di TCustomRemoteServer e si 
differenziano principalmente per il protocollo di comunicazione utilizzato (TCP/IP, 
HTTP, DCOM, SOAP o CORBA). Collegare il dataset client con il suo componente 
connection impostandone la proprieta RemoteServer. 

II componente connection stabilisce una connessione con l'application server e 
restituisce un'interfaccia che viene utilizzata dal dataset client per chiamare il 
provider specificato mediante la sua proprieta ProviderName. Ogni volta che il dataset 
client chiama l'application server, passa il valore di ProviderName e il server 
applicazione inoltra la chiamata al provider. 

Per ulteriori informazioni sulla connessione di un dataset client a un application 
server, consultare il Capitolo 29, "Creazione di applicazioni multi-tier". 

Combinazione dei vari approcci 



Le sezioni precedenti descrivono numerose architetture che e possibile utilizzare 
quando si scrivono applicazioni database. Non c'e alcun motivo, tuttavia, che 
impedisce di combinare due o piu delle architetture disponibili in una singola 
applicazione. Infatti, alcune combinazioni possono essere estremamente potenti. 

Ad esempio, e possibile combinare l'architettura basata su disco descritta nel 
paragrafo "Utilizzo di un file dedicato su disco" a pagina 18-9 con un altro approccio 
come quelli descritti in "Connessione di un dataset client a un altro dataset nella 
stessa applicazione" a pagina 18-12 oppure in "Utilizzo di un'architettura multi-tier" 
a pagina 18-13. Queste combinazioni sono semplici perche tutti i modelli utilizzano 
un dataset client per rappresentare i dati che vengono visualizzati nell'interfaccia 
utente. II risultato e definito modello briefcase (o talvolta modello non connesso, o 
mobile computing). 

II modello briefcase e utile in una situazioni come quella descritta di seguito: Un 
database aziendale contiene i dati relativi ai contatti dei clienti che i rappresentanti 
possono utilizzare e aggiornare mentre operano sul campo. Durante la loro 
permanenza in sede, i rappresentanti scaricheranno le informazioni dal database. 
Successivamente, lavoreranno sui dati con i loro computer portatili durante gli 
spostamenti attraverso il paese e potranno anche aggiornare i record mentre saranno 
presso la sede dei nuovi o dei clienti esistenti. Una volta tornati in sede, i 
rappresentanti dovranno caricare nel database aziendale le proprie modifiche ai dati, 
affinche siano utilizzabili da tutti. 

Durante le operazioni in sede, il dataset client di un'applicazione che segue il 
modello briefcase reperira i dati utilizzando un provider. II dataset client e quindi 
connesso al server di database e pud, tramite il provider, prendere i dati del server e 
restituire gli aggiornamenti al server. Prima di scollegarsi dal provider, il dataset 
client salva l'istantanea delle informazioni in un file su disco. Durante le operazioni 
fuori sede, il dataset client carica i dati dal file e salva le eventuali modifiche in quel 
file. Infine, tomato di nuovo in sede, il dataset client si riconnette al provider in modo 
da applicare gli aggiornamenti al server di database o aggiornare la propria 
istantanea dei dati. 
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Progettazione dell'interfaccia utente 



La pagina Data Controls della Component palette fornisce una serie di controlli 
associati ai dati che rappresentano i dati dei campi in un record del database, e puo 
permettere agli utenti di modificare questi dati e di inoltrare le modifiche al database 
stesso. Usando i controlli associati ai dati, e possibile costruire l'interfaccia utente 
(UI) dell'applicazione database in modo che le informazioni siano visibili e accessibili 
agli utenti. Per ulteriori informazioni sui controlli data-aware, consul tare il Capitolo 
19, "Uso dei controlli dati". 

Oltre ai controlli dati di base, potrebbe essere necessario introdurre nell'interfaccia 
utente altri elementi: 

• Potrebbe essere necessario che l'applicazione analizzi i dati contenuti in un 
database. Le applicazioni che analizzano dati non si limitano semplicemente a 
visualizzare i dati in un database, ma compongono anche le informazioni in 
forma ti atti ad aiutare gli utenti a percepire il significato intrinseco di quei dati. 

• Potrebbe essere necessario stampare dei report in modo da fornire una copia 
cartacea delle informazioni visualizzate nell'interfaccia utente. 

• Potrebbe essere necessario creare un'interfaccia utente visualizzabile tramite un 
Web browser. Alcune semplici applicazioni database basate su Web sono descritte 
in "Utilizzo nelle risposte di informazioni di database" a pagina 33-18. Inoltre, e 
possibile combinare l'approccio basato su Web con l'architettura multi-tier, come 
descritto in "Scrittura di applicazioni client basate su Web". 

Analisi dei dati 



Alcune applicazioni database non presentano le informazioni del database 
direttamente all'utente. Esse analizzano e riassumono, invece, le informazioni dai 
database in modo che gli utenti possano trarre conclusioni dai dati. 

II componente TDBChart nella pagina Data Controls della Component palette 
permette di presentare le informazioni del database in un formato grafico che 
consente agli utenti di cogliere rapidamente il senso delle informazioni del database. 

Inoltre, alcune versioni di C++Builder includono nella Component palette una 
pagina Decision Cube. Questa pagina contiene sei componenti che permettono di 
eseguire l'analisi e il confronto incrociato dei dati durante la creazione di 
applicazioni per il supporto decisionale. Per ulteriori informazioni sull'uso dei 
componenti Decision Cube, consultare il Capitolo 20, "Uso dei componenti di 
supporto decisionale". 

Se si desidera costruire propri componenti in grado di visualizzare riepiloghi di dati 
in base a diversi criteri di raggruppamento, e possibile usare le aggregazioni di 
manutenzione con un dataset client. Per ulteriori informazioni sull'uso delle 
aggregazioni di manutenzione, consultare "Uso delle aggregazioni di 
manutenzione" a pagina 27-12. 
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Scrittura di report 



Per consentire agli utenti di stampare le informazioni del database dai dataset 
nell'applicazione, si possono usare i componenti report della pagina QReport della 
Component palette. Usando questi componenti, si possono costruire in modo visuale 
report suddivisi in bande per presentare e sintetizzare le informazioni contenute 
nelle tabelle del database. E possibile aggiungere riepiloghi per raggruppare 
intestazioni o pie pagina in modo da analizzare i dati in base a criteri di 
r aggr upp amento . 

Per creare un report per l'applicazione, selezionare l'icona QuickReport dalla finestra 
di dialogo New Items. Selezionare File I NewXOther dal menu principale e 
richiamare la pagina Business. Per awiare il wizard, fare doppio clic sull'icona 
QuickReport Wizard. 

Per un esempio di come utilizzare i componenti presenti sulla pagina QReport, 
esaminare il programma di esempio QuickReport fornito con C++Builder. 
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Capitolo 



19 



Uso dei 



controlli dati 



La pagina Data Controls della Component palette fornisce un insieme di controlli 
data-aware per rappresentare i dati dei campi di un record di un database e, se il 
dataset lo permette, consente agli utenti di modificare quei dati e di registrare le 
modifiche nel database. Collocando sulle schede dell'applicazione database questi 
controlli per dati e possibile costruire l'interfaccia utente (UI) dell'applicazione 
database in modo da rendere visibili e accessibili agli utenti tali informazioni. 

I controlli data-aware che vengono aggiunti aU'interfaccia utente dipendono da 
numerosi fattori, tra cui: 

• II tipo di dati da visualizzare. E possibile scegliere fra controlli progettati per 
visualizzare e modificare un testo non formattato, controlli che operano con testo 
formattato, controlli per la grafica, elementi multimediali e cosi via. I controlli che 
visualizzano vari tipi di informazioni sono descritti in "Visualizzazione di un 
singolo record" a pagina 19-8. 

• Come si vogliono organizzare le informazioni. E possibile scegliere di visualizzare 
le informazioni contenute in un singolo record o di elencare le informazioni 
contenute in piu record utilizzando una griglia. II paragrafo "Scelta del modo in 
cui organizzare i dati" a pagina 19-8 descrive alcune possibilita. 

• II tipo di dataset che fornisce i dati ai controlli. Si potrebbero utilizzare controlli 
che riflettano le limitazioni del dataset sottostante. Ad esempio, non si utilizzera 
mai una griglia con un dataset unidirezionale perche i dataset unidirezionali 
possono fornire solo un singolo record per volta. 

• Come (o se) si desidera consentire agli utenti di spostarsi tra i record dei dataset e 
aggiungere o modificare i dati. Si potrebbero aggiungere controlli o meccanismi 
personali per spostarsi tra i record e modificarli oppure si potrebbe utilizzare un 
controllo nativo come programma per la navigazione tra i dati. Per ulteriori 
informazioni sull'utilizzo di un componente per la navigazione tra i dati, vedere 
"Spostamento e gestione dei record" a pagina 19-31. 
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Uso d e 1 1 e funzioni comuni ai controlli dati 



Controlli data-aware piu complessi per il supporto decisionale sono descritti nel 
Capitolo 20, "Uso dei componenti di supporto decisionale". 

Indipendentemente dai controlli data-aware che si sceglie di aggiungere 
all'interfaccia, si applicano alcune funzionalita comuni. Queste sono descritti nel 
prosieguo del capitolo. 



Uso delle funzioni comuni ai controlli dati 



Le seguenti operazioni sono comuni alia maggior parte dei controlli dati: 

• Associazione di un controllo dati a un dataset 

• Modifica e aggiornamento dei dati 

• Disabilitazione e abilitazione della visualizzazione dei dati 

• Aggiornamento della visualizzazione dei dati 

• Abilitazione degli eventi mouse, tastiera e timer 

I controlli dati consentono di visualizzare e di modificare i campi dati associati al 
record attivo in un dataset. La Tabella 19.1 riepiloga i controlli dati che appaiono 
nella pagina Data Controls della Component palette. 



Tabella 19.1 Controllo dati 
Controllo dati 

TDBGrid 



TDBNavigator 

TDBText 
TDBEdit 
TDBMemo 

TDBImage 
TDBListBox 

TDBComboBox 

TDBCheckBox 
TDBRadioGroup 

TDBLookupListBox 

TDBLookupComboBox 



Descrizlone 

Mostra informazioni da una sorgente dati in formato tabellare. Le 
colonne della griglia corrispondono alle colonne della tabella associata o 
al dataset della query. Le righe della griglia corrispondono ai record. 

Consente di spostarsi tra i record di dati di un dataset, di aggiornare i 
record, di confermarli, di cancellare le modifiche e di aggiornare la 
visualizzazione dei dati. 

Mostra dati tratti da un campo sotto forma di etichetta. 

Mostra dati tratti da un campo in una casella di teste 

Mostra dati tratti da un campo memo o BLOB in una casella di testo 
multirighe. 

Mostra grafici di un campo dati in una casella grafica. 

Mostra una lista di elementi da cui effettuare una scelta per aggiornare 
un campo nel record dati attivo. 

Mostra una lista di elementi fra cui scegliere per aggiornare un campo e 
consente inoltre di immettere direttamente un testo come in una casella 
di testo associata ai dati standard. 

Mostra una casella di controllo che indica il valore di un campo booleano. 

Mostra una serie di opzioni per il campo, che si escludono 
reciprocamente. 

Mostra una lista di elementi cercati in un altro dataset in base al valore di 
un campo. 

Mostra una lista di elementi cercati in un altro dataset in base al valore di 
un campo; consente, inoltre, di immettere direttamente un testo come in 
una casella standard di testo associata ai dati. 
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Tabella 19.1 Controllo dati (continua) 
Controllo dati Descrizione 

TDBCtrlGrid Mostra, all'interno di una griglia, un insieme di controlli associati ai dati 

configurabili e ripetitivi. 

TDBRichEdit Mostra dati formattati di un campo in una casella di testo. 

I controlli dati vengono associati ai dati in fase di progetto. Quando si associa un 
controllo dati con un dataset attivo durante la creazione di un'applicazione, nel 
controllo e possibile vedere immediatamente dati dinamici. In fase di progetto e 
possibile utilizzare il Fields Editor per effettuare lo scorrimento attraverso un dataset 
e verificare che l'applicazione visualizzi i dati correttamente, senza doverla 
compilare ed eseguire. Per ulteriori informazioni su Fields Editor, vedere "Creazione 
di campi persistenti" a pagina 23-4. 

In fase di esecuzione i controlli dati visualizzano i dati che l'utente puo modificare 
tramite il controllo, nel caso l'applicazione, il controllo e il dataset lo consentano. 

Associazione di un controllo dati a un dataset 



I controlli dati si collegano ai dataset usando un datasource. Un componente 
datasource (TDataSource) si comporta come un elemento di connessione tra il 
controllo e un dataset contenente dati. Ogni controllo data-aware deve essere 
associato a un componente datasource per poter avere dei dati da visualizzare e 
trattare. Analogamente, tutti i dataset devono essere associati a un componente 
datasource affinche i relativi dati siano visualizzati e trattati nei controlli data-aware 
di una scheda. 

I componenti Datasource sono necessari anche per collegare dataset non annidati 
nelle relazioni master-detail. 

Per associare un controllo dati a un dataset: 

1 Collocare un dataset in un modulo dati (o su una scheda) impostarne in modo 
adeguato le proprieta. 

2 Collocare un datasource nello stesso modulo dati (o scheda). Utilizzando l'Object 
Inspector, impostarne la proprieta DataSet al nome del dataset collocato al punto 1. 

3 Inserire un controllo dati dalla pagina Data Access della Component palette in una 
scheda. 

4 Utilizzando l'Object Inspector, impostare la proprieta DataSource del controllo al 
datasource del componente collocato al punto 2. 

5 Impostare la proprieta DataField del controllo al nome di un campo da 
visualizzare, o selezionare un nome di campo dall'elenco a comparsa della 
proprieta. Questa fase non vale per a TDBGrid, TDBCtrlGrid, e TDBNavigator 
perche accedono a tutti i campi disponibili nel dataset. 

6 Impostare la proprieta Active del dataset a true per visualizzare i dati del controllo. 
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Modifica del dataset associato in esecuzione 

Nell'esempio precedente, il datasource e stato associato al proprio dataset 
impostando la proprieta DataSet in fase di progettazione. In fase di esecuzione, se 
occorre, e possibile scambiare il dataset di un componente datasource. Ad esempio, il 
codice seguente commuta il dataset del componente datasource CustSource tra i 
componenti dataset di nome Customers e Orders: 

if (CustSource->DataSet == Customers) 

CustSource->DataSet = Orders; 
else 

CustSource->DataSet = Customers; 

E possibile anche impostare la proprieta DataSet al dataset di un'altra scheda in modo 
da sincronizzare i controlli dati sulle due schede. Per esempio: 

void fastcall TForm2: :FormCreate(TObject *Sender) 

{ 

DataSourcel->DataSet = Forml->Tablel; 

} 

Attivazione e disattivazione del datasource 

II datasource ha una proprieta Enabled che determina se e connesso al proprio 
dataset. Se Enabled e true, il datasource e connesso al dataset. 

E possibile sconnettere temporaneamente un singolo datasource dal suo dataset 
impostando Enabled su false. Quando Enabled e false, tutti i controlli dati connessi al 
componente datasource diventano vuoti e inattivi finche Enabled non e impostato a 
true. E consigliabile, tuttavia, controllare l'accesso a un dataset tramite i metodi 
DisableControls e EnableControls di un componente dataset in quanto essi influenzano 
tutti i datasource collegati. 

Risposta alle modifiche mediate dal datasource 

Poiche il datasource fornisce il collegamento tra il controllo dati e il proprio dataset, 
esso funge da intermediario per tutte le comunicazioni che awengo tra i due. Di 
solito, il controllo data-aware risponde automaticamente alle modifiche nel dataset. 
Tuttavia, se l'interfaccia utente utilizza controlli che non sono data-aware, e possibile 
utilizzare gli eventi di un componente datasource per fornire manualmente lo stesso 
tipo di risposta. 

L'evento OnDataChange si verifica ogni volta che i dati in un record possono aver 
subito un cambiamento, sia per la modifica del campo sia perche il cursore passa su 
un nuovo record. Questo evento risulta utile per assicurarsi che il controllo rifletta i 
valori correnti del campo nel dataset, in quanto viene attivato da tutte le modifiche. 
Di solito, un gestore di evento OnDataChange viene utilizzato per aggiornare il valore 
di un controllo non data-aware che visualizza i dati di un campo. 

L'evento OnllpdateData si verifica nel momento in cui si stanno per registrare i dati 
nel record corrente. Per esempio, si verifica un evento OnllpdateData dopo che viene 
chiamato Post, ma prima che i dati vengano effettivamente registrati nel server di 
database sottostante o nella cache locale. 
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L'evento OnStateChange si verifica quando cambia lo stato del dataset. Quando si 
verifica questo evento, e possibile esaminare la proprieta State del dataset per 
determinarne lo stato corrente. 

Per esempio, il seguente gestore di evento OnStateChange attiva o disattiva i pulsanti 
o le voci di menu in base alio stato corrente: 

void __fastcall TForral : :DataSourcelStateChange (TObject *Sender) 
{ 

CustTableActivateBtn->Enabled = (CustTable->State == dslnactive) ; 
CustTableEditBtn->Enabled = (CustTable->State == dsBrowse); 
CustTableCancelBtn->Enabled = (CustTable->State == dslnsert I 

CustTable->State == dsEdit I 

CustTable->State == dsSetKey) ; 

} 

Per ulteriori informazioni sugli stati del dataset, consultare "Determinazione degli 
stati del dataset" a pagina 22-3. 



Modifica e aggiornamento dei dati 



Tutti i controlli dati, tranne il navigatore, visualizzano i dati di un campo database. 
Inoltre, possono essere utilizzati per modif icare e aggiornare i dati finche il dataset 
sottostante lo permette. 

I dataset unidirezionali non consentono mai all'utente di modificare e aggiornare i 
dati. 

Abilitazione dell'editing nei controlli all'atto dell'immissione dati 

Un dataset deve essere in stato dsEdit perche sia possibile modificarne i dati. Se la 
proprieta AutoEdit del datasource e true (impostazione predefinita), il controllo dati 
gestisce l'attivita di porre il dataset in modalita dsEdit non appena l'utente prova a 
modificarne i dati. 

Se AutoEdit e false, e necessario fornire un meccanismo alternativo per porre il 
dataset in modalita editing. Un possibile meccanismo consiste nell'utilizzare un 
controllo TDBNavigator con un pulsante Edit che consenta esplicitamente all'utente di 
porre il dataset in modalita editing. Per ulteriori informazioni su TDBNavigator, 
vedere "Spostamento e gestione dei record" a pagina 19-31. In alternativa, e possibile 
scrivere del codice che chiami il metodo Edit del dataset quando si desidera porre il 
dataset in modalita editing. 

Modifica dei dati in un controllol 

Un controllo dati puo registrare le modifiche apportate al dataset associato solo se la 
proprieta CanModify del dataset e true. CanModify e sempre false per i dataset 
unidirezionali. Alcuni dataset hanno una proprieta ReadOnly che consente di 
specificare se CanModify e true. 

II fatto che un dataset client possa aggiornare i dati dipende dal fatto che la tabella 
del database sottostante consenta o meno gli aggiornamenti. 
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Anche se la proprieta CanModify del dataset e impostata a true, affinche il controllo 
possa registrare gli aggiornamenti nella tabella di database, e necessario impostare a 
true anche la proprieta Enabled del datasource che connette il dataset al controllo. La 
proprieta Enabled del datasource determina se il controllo puo visualizzare i valori 
dei campi del dataset e, di conseguenza, se un utente puo modificare i valori e 
registrare le modifiche. Se Enabled e true (impostazione predefinita), i controlli 
possono visualizzare i valori dei campi. 

Infine, e possibile controllare anche se l'utente puo apportare modifiche ai dati 
visualizzati nel controllo. La proprieta ReadOnly del controllo dati determina se un 
utente puo modificare i dati visualizzati dal controllo. Se e false (impostazione 
predefinita), gli utenti possono modificare i dati. Ovviamente, sara bene assicurarsi 
che la proprieta ReadOnly del controllo sia true quando la proprieta CanModify del 
dataset e false. In caso contrario, si dara falsamente all'utente l'impressione che possa 
influire sui dati nella tabella del database sottostante. 

In tutti i controlli dati, ad eccezione di TDBGrid, le modifiche apportate a un campo 
vengono copiate nel componente field sottostante in un dataset quando viene 
premuto il tasto Tab dal controllo. Se in un campo si preme Esc prima di Tab, il 
controllo dati abbandona le modifiche e ripristina il valore del campo antecedente 
alle modifiche. 

In TDBGrid, le modifiche vengono confermate solo quando si passa a un altro record; 
per annullare tutte le modifiche apportate a un qualsiasi record di un campo, e 
possibile premere Esc prima di passare a un altro record. 

Quando un record viene registrato, C++Builder controlla tutti i componenti data- 
aware associati al dataset, per verificare se il loro stato e cambiato. Se sorge un 
problema di aggiornamento di un campo contenente dati modificati, C++Builder 
solleva un'eccezione e il record non viene modificato. 

Se l'applicazione memorizza gli aggiornamenti nella cache (ad esempio, utilizzando 
un dataset client), tutte le modifiche vengono inviate a una cache interna. Queste 
modifiche non vengono applicate alia tabella di database sottostante finche non si 
chiama il metodo Applyllpdates del dataset. 

Disabilitazione e abilitazione della visualizzazione dei dati 



Quando l'applicazione elabora in sequenza un dataset o esegue una ricerca, e 
opportuno impedire temporaneamente l'aggiornamento dei valori visualizzati nei 
controlli associati ai dati a ogni variazione del record attivo. Impedendo 
l'aggiornamento dei valori, l'operazione sequenziale o la ricerca risultano piu veloci e 
si evita il fastidioso sfarfallio dello schermo. 

DisableControls e un metodo dei dataset che disabilita la visualizzazione di tutti i 
controlli associati ai dati legati a un dataset. Non appena sono terminate 
l'elaborazione sequenziale o la ricerca, l'applicazione deve chiamare 
immediatamente il metodo EnableControls del dataset per abilitare nuovamente la 
visualizzazione nei controlli. 

Di solito, i controlli vengono disabilitati prima di iniziare un processo iterativo. 
Quest'ultimo deve aver luogo all'interno di un'istruzione try. ..finally, in modo che 
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sia possibile riabilitare i controlli anche se si verifica un'eccezione durante 
l'elaborazione. La clausola finally chiamera EnableControls. II codice seguente illustra 
come utilizzare DisableControls e EnableControls in questo modo: 

CustTable->DisableControls ( ) ; 
try 

{ 

// cycle through all records of the dataset 

for (CustTable->First() ; !CustTable->EOF; CustTable->Next ( ) ) 

{ 

// Process each record here 
} 

} 

__finally 

{ 

CustTable->EnableControls ( ) ; 

} 

Aggiornamento della visualizzazione dei dati 



II metodo Refresh di un dataset svuota i buffer locali e recupera nuovamente i dati per 
un dataset aperto. Questo metodo puo essere usato per aggiornare la visualizzazione 
nei controlli data-aware, qualora si ritenga che i dati sottostanti possano essere stati 
modificati da altre applicazioni che hanno accesso simultaneo agli stessi dati. Se si 
stanno utizzando gli aggiornamenti tramite cache, prima di aggiornare il dataset e 
necessario applicare tutti gli aggiornamenti che il dataset ha attualmente 
memorizzato nella cache. 

L'aggiornamento puo talvolta comportare risultati imprevisti. Per esempio, se un 
utente visualizza un record che e stato cancellato da un'altra applicazione, il record 
scomparira nel momento in cui l'applicazione chiama Refresh. I dati possono, inoltre, 
sembrare diversi se un altro utente cambia un record nel periodo di tempo che 
intercorre fra il primo recupero dei dati e il momento in cui si chiama il metodo 
Refresh. 

Abilitazione degli eventi mouse, tastiera e timer 



La proprieta Enabled di un controllo dati determina se quest'ultimo risponde a eventi 
mouse, tastiera o timer e passa informazioni alia propria sorgente dati. 
L'impostazione predefinita di questa proprieta e true. 

Per impedire che gli eventi mouse, tastiera o timer arrivino a un controllo dati, la 
proprieta Enabled deve essere impostata a false. Quando Enabled e false, il datasource 
che collega il controllo al proprio dataset non riceve informazioni dal controllo dati. 
Quest'ultimo continua a visualizzare i dati, ma il testo presentato nel controllo non 
puo essere modificato. 
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Scelta del modo in cui organizzare i dati 



Quando si costruisce l'interfaccia utente per l'applicazione database, si ha la 
possibility di organizzare a proprio piacimento la visualizzazione delle informazioni 
e i controlli che trattano quelle informazioni. 

Una delle prime decisioni da prendere e quella relativa al fatto che si voglia 
visualizzare un singolo record per volta o piu record contemporaneamente. 

Inoltre, si vorranno aggiungere dei controlli per spostarsi tra i record e per trattarli. II 
controllo TDBNavigator fornisce un supporto nativo per la maggior parte delle 
operazioni che si potrebbero compiere. 

Visualizzazione di un singolo record 



In molte applicazioni, potrebbe essere opportuno fornire informazioni su un singolo 
record di dati per volta. Ad esempio, un'applicazione per l'immisione di ordini 
potrebbe visualizzare le informazioni relative a un singolo ordine senza indicare 
quali altri ordini sono attualmente registrati. Probabilmente queste informazioni 
provengono da un singolo record in un dataset di ordini. 

Di solito, le applicazioni che visualizzano un singolo record risultano facili da leggere 
e da capire, perche tutte le informazioni del database sono relative alio stesso 
elemento (nel caso precedente, lo stesso ordine). I controlli data-aware in queste 
interfacce utente rappresentano un singolo campo di un record del database. La 
pagina Data Controls della Component palette fornisce un'ampia scelta di controlli 
per rappresentare vari tipi di campi. Di solito questi controlli sono versioni data- 
aware di altri controlli disponibili nella Component palette. Ad esempio, il controllo 
TDBEdit e una versione data-aware del controllo standard TEdit che consente agli 
utenti di visualizzare e modificare una stringa di testo. 

La scelta del controllo da utilizzare dipende dal tipo di dati (testo, testo formattato, 
immagini, informazioni booleane e cosi via) contenuti nel campo. 

Visualizzazione dei dati come etichette 

TDBText e un controllo a sola lettura simile al componente TLabel sulla pagina 
Standard della Component palette. Un controllo TDBText e utile quando si vogliono 
fornire dati unicamente da visualizzare su una scheda che consente l'immissione dati 
da parte dell'utente negli altri controlli. Si supponga, per esempio, di creare una 
scheda sui campi in una tabella di un elenco clienti e che, una volta che l'utente ha 
immesso le informazioni relative a un indirizzo, una citta e uno stato o provincia 
nella scheda, si usi un consultazione dinamica per determinare automaticamente il 
campo codice postale da una tabella separata. Per visualizzare il campo relativo al 
codice postale corrispondente all'indirizzo immesso dall'utente, si potrebbe usare un 
componente TDBText legato alia tabella dei codici postali. 

TDBText ricava il testo che visualizza da un campo specificato del record attivo di un 
dataset. Poiche TDBText preleva il testo da un dataset, il testo visualizzato e 
dinamico, owero cambia via via che l'utente si sposta nella tabella di database. Non e 
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pertanto possibile specificare il testo che TDBText deve visualizzare in fase di 
progetto, come avviene con TLabel. 

Quando si inserisce in una scheda un componente TDBText, verificare che la relativa 
proprieta AutoSize sia true (impostazione predefinita) in modo che il controllo adatti 
automaticamente la propria dimensione per contenere dati di dimensione variabile. 
Se AutoSize e false e il controllo e troppo piccolo, i dati visualizzati vengono troncati. 

Visualizzazione e modifica di campi in una casella di testo 

TDBEdit e una versione associata ai dati di un componente casella di testo. TDBEdit 
visualizza il valore attivo di un campo dati al quale e collegato e ne consente la 
modifica con le tecniche standard delle caselle di testo. 

Per esempio, si supponga che CustomersSource sia un componente TDataSource attivo, 
collegato a un componente TClientDataSet aperto, di nome Customer sT able. Un 
componente TDBEdit potra essere inserito in una scheda e le sue proprieta potranno 
essere impostate come segue: 

• DataSource: CustomersSource 

• DataField: CustNo 

II componente casella di testo associato ai dati visualizza il valore della riga attiva 
della colonna CustNo del dataset CustomersTable, sia in fase di progetto sia in fase di 
esecuzione. 

Visualizzazione e modifica del testo in un controllo memo I 

TDBMemo e un componente associato ai dati, simile al componente standard TMemo- 
che puo visualizzare dati di testo molto lunghi. TDBMemo visualizza il testo su piu 
righe e consente a un utente di immettere testo su piu righe. I controlli TDBMemo 
possono servire per visualizzare campi di testo molto lunghi e dati di testo contenuti 
in campi BLOB (Binary Large OBject). 

Per impostazione predefinita, TDBMemo permette a un utente di modificare il testo 
del campo memo. Per impedire la modifica, impostare la proprieta ReadOnly del 
controllo memo a true. Per visualizzare i caratteri di tabulazione e permettere agli 
utenti di registrar li in un campo memo, impostare la proprieta WantTabs a true. Per 
limitare il numero di caratteri che l'utente puo immettere nel campo memo del 
database, usare la proprieta MaxLength. II valore predefinito per MaxLength e 0, che 
indica che non esiste alcun limite per i caratteri, tranne quello imposto dal sistema 
operativo. 

Diverse proprieta determinano il modo in cui si presenta il memo del database e 
viene immesso il testo. Con la proprieta ScrollBars e possibile inserire barre di 
scorrimento nel memo. Per impedire il ritorno a capo automatico, impostare la 
proprieta WordWrap a false. La proprieta Alignment determina la modalita di 
allineamento del testo all'interno del controllo. Scelte possibili sono taLeftJustify 
(impostazione predefinita), taCenter e taRight Justify. Per cambiare il carattere del 
testo, utilizzare la proprieta Font. 

In fase di esecuzione gli utenti possono eseguire operazioni di taglio, copia e 
incollaggio di testo in un controllo memo di database. Le stesse operazioni possono 
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essere svolte da programma ricorrendo ai metodi CutToClipboard, CopyToClipboard, e 
PasteFromClipboard. 

Poiche TDBMemo puo visualizzare grossi volumi di dati, la visualizzazione completa 
durante l'esecuzione puo richiedere del tempo. Per ridurre il tempo necessario per 
scorrere i record dei dati, TDBMemo dispone di una proprieta AutoDisplay che 
controlla se i dati ai quali si accede devono essere visualizzati automaticamente. Se si 
imposta AutoDisplay a false, invece dei dati effettivi TDBMemo visualizza il nome di 
campo. Per visualizzare i dati veri e propri, fare doppio clic all'interno del controllo. 

Visualizzazione e modifica del testo in un controllo rich edit 

TDBRichEdit e un componente associato ai dati-simile al componente standard 
TRichEdit-che puo visualizzare del testo formattato memorizzato in un campo BLOB 
(binary large object ). TDBRichEdit visualizza il testo formattato su piu righe e 
consente all'utente di inserire del testo dello stesso tipo. 

Benche TDBRichEdit fornisca proprieta e metodi per immettere dati e lavorare con un 
Rich Text, non fornisce nessun componente di interf accia utente per rendere 
disponibili all'utente queste opzioni di configurazione. L'applicazione deve 
implementare l'interfaccia utente per rendere evidenti le capacita relative ai Rich 
Text. 

Per impostazione predefinita, TDBRichEdit permette a un utente di modificare un 
testo di un campo memo. Per impedire la modifica, impostare la proprieta ReadOnly 
del controllo a true. Per visualizzare i caratteri di tabulazione e permettere agli utenti 
di registrarli in un campo memo, impostare la proprieta WantTabs a true. Per limitare 
il numero di caratteri che l'utente puo immettere nel campo memo del database, 
usare la proprieta MaxLength. II valore predefinito per MaxLength e 0, che indica che 
non esiste alcun limite per i caratteri, tranne quello imposto dal sistema operativo. 

Poiche TDBRichEdit puo visualizzare grossi volumi di dati, la visualizzazione 
completa durante l'esecuzione puo richiedere del tempo. Per ridurre il tempo 
necessario a scorrere i record dei dati, TDBRichEdit dispone di una proprieta 
AutoDisplay che controlla se i dati ai quali si accede devono essere visualizzati 
automaticamente. Se si imposta AutoDisplay a false, invece dei dati effettivi 
TDBRichEdit visualizza il nome di campo. Per visualizzare i dati veri e propri, fare 
doppio clic all'interno del controllo. 

Visualizzazione e modifica di campi grafici in un controllo immagine 

TDBImage e un controllo associato ai dati che consente di visualizzare dati grafici 
contenuti in campi BLOB. 

Per impostazione predefinita, TDBImage permette di modificare un'immagine con 
operazioni di taglia e incolla, dagli e negli Appunti, utilizzando i metodi e 
CutToClipboard, CopyToClipboard , e PasteFromClipboard. E possibile, invece, creare dei 
propri metodi per l'editing associati ai gestori di evento del controllo. 

Per impostazione predefinita, un controllo immagine visualizza l'immagine fino a 
riempire completamente il controllo, ritagliando l'immagine nel caso sia troppo 
grande. E possibile impostare la proprieta Stretch a true per dimensionare il grafico in 
funzione della dimensione del controllo dell'immagine. 
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Poiche TDBImage puo visualizzare quantita ingenti di dati, la visualizzazione 
completa durante l'esecuzione puo richiedere del tempo. Per ridurre il tempo 
richiesto per effettuare lo scorrimento dei record di dati, TDBImage ha una proprieta 
AutoDisplay che determina se i dati ai quali si accede devono essere visualizzati 
automaticamente. Se AutoDisplay e impostata a false, TDBImage visualizza il nome 
del campo invece dei dati effettivi. Per visualizzare i dati veri e propri, fare doppio 
clic all'interno del controllo. 

Visualizzazione e modifica di dati in caselle combinate e di riepilogo 

Esistono quattro controlli dati che presentano all'utente, in fase di esecuzione, un 
insieme di valori predefiniti fra cui effettuare una scelta. I controlli seguenti sono le 
versioni data-aware dei controlli standard casella di riepilogo e casella combinata: 

• TDBListBox, che visualizza una lista a scorrimento di elementi di cui l'utente ne 
puo selezionare uno da immettere in un campo dati. Una casella di riepilogo data- 
aware visualizza un valore predefinito per un certo campo del record corrente e ne 
evidenzia la voce corrispondente nella lista. Se il valore del campo della riga 
corrente non e incluso nella lista, nella casella di riepilogo non viene evidenziato 
alcun valore. Quando un utente seleziona un elemento dell'elenco, il valore del 
campo corrispondente nel dataset sottostante viene modificato. 

• TDBComboBox, che combina le funzionalita di un controllo data-aware per 
l'editing e di una lista a discesa. In fase di esecuzione puo visualizzare un elenco a 
comparsa nel quale l'utente puo scegliere uno dei valori predefiniti oltre a 
consentire l'immissione di un valore completamente diverso. 

• TDBLookupListBox, che si comporta come TDBListBox tranne per il fatto che la lista 
degli elementi visualizzati viene cercata in un altro dataset. 

• TDBLookupComboBox, che si comporta come TDBComboBox tranne per il fatto che 
la lista degli elementi visualizzati viene cercata in un altro dataset. 

In fase di esecuzione gli utenti possono utilizzare la ricerca incrementale per trovare 
gli elementi di una casella di riepilogo. Quando il controllo ha il fuoco, ad esempio, 
inserendo 'ROB' si seleziona la prima voce della casella di riepilogo che inizia con le 
lettere 'ROB'. Se si immette un ulteriore carattere 'E', sara selezionato il primo 
elemento che inizia con 'ROBE', ad esempio 'Robert Johnson'. La ricerca non 
distingue tra caratteri maiuscoli e minuscoli. Backspace ed Esc annullano la stringa di 
ricerca corrente (ma lasciano intatta la selezione), analogamente a una pausa di due 
secondi tra un tasto e l'altro. 

Utilizzo di TDBListBox e TDBComboBox 

Quando si utilizzano TDBListBox o TDBComboBox, e necessario utilizzare in 
progettazione lo String List editor per creare l'elenco degli elementi da visualizzare . 
Per visualizzare lo String List editor, fare clic nell'Object Inspector sul pulsante ellissi 
della proprieta Items .Quindi inserire nella lista gli elementi che si desidera 
visualizzare. In esecuzione, utilizzare i metodi della proprieta Items per trattare la 
lista di stringhe. 

Quando un controllo TDBListBox o TDBComboBox e collegato con un campo tramite 
la proprieta DataField, il valore del campo viene visualizzato nella lista come 
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selezionato. Se il valore corrente non e nella lista, non viene visualizzato come 
selezionato alcun elemento. Tuttavia, TDBComboBox visualizza il valore corrente del 
campo nella casella di modifica, indipendentemente dal fatto che sia visualizzato o 
meno nella lista Items. 

In TDBListBox, la proprieta Height determina quanti elementi sono visibili 
contemporaneamente nella casella di riepilogo. La proprieta IntegmlHeight controlla 
il modo in cui potra essere visualizzato l'ultimo elemento. Se IntegmlHeight e false 
(impostazione predefinita), la parte inferiore della casella di riepilogo e determinata 
dalla proprieta ItemHeight e l'ultimo elemento potrebbe non essere visualizzato 
completamente. Se IntegralHeight e true, anche l'ultimo elemento della casella di 
riepilogo e visualizzato per intero. 

In TDBComboBox, la proprieta SfyZedetermina interazione dell'utente con il controllo. 
Per impostazione predefinita, Style e csDropDown, il che significa che un utente pud 
immettere valori da tastiera oppure scegliere un elemento dalla lista a discesa. Le 
seguenti proprieta determinano la modalita di visualizzazione dell'elenco Items in 
fase di esecuzione: 

• Style determina lo stile di visualizzazione del componente: 

• csDropDown (impostazione predefinita): visualizza un elenco a comparsa con 
una casella di testo in cui l'utente puo immettere un testo. Tutte le voci sono 
stringhe e hanno la stessa altezza. 

• csSimple: combina un casella di testo con un elenco di elementi aventi 
dimensioni fisse che viene sempre visualizzato. Quando si imposta Style a 
csSimple, accertarsi di aumentare la proprieta Height in modo che l'elenco venga 
visualizzato. 

• csDropDownList: visualizza un elenco a comparsa e una casella di testo, ma in 
fase di esecuzione l'utente non puo immettere o modificare valori che non siano 
nell'elenco a comparsa. 

• csOwnerDmwFixed and csOwnerDrawVariable: consente all'elenco di elementi di 
visualizzare valori che non siano stringhe (per esempio, immagini bitmap) o di 
usare font differenti per i singoli elementi dell'elenco 

• DropDownCount: indica il numero massimo di elementi che possono essere 
visualizzati nell'elenco. Se il numero di elementi contenuti in Items e maggiore di 
quello indicato in DropDownCount, l'utente puo effettuare lo scorrimento 
dell'elenco. Se il numero di elementi contenuti in Items e minore di quello indicato 
in DropDownCount, l'elenco sara sufficientemente grande per visualizzare tutte le 
voci contemporaneamente. 

• ItemHeight: indica l'altezza di ciascun elemento quando lo stile e 

csOwnerDrawFixed. 

• Sorted: se e true, gli elementi dell'elenco Items sono visualizzati in ordine 
alfabetico. 

Visualizzazione e modifica di dati in liste e caselle combinate di consultazione 

Le caselle di riepilogo di consultazione e le caselle combinate di consultazione 
(TDBLookupListBox e TDBLookupComboBox) presentano all'utente a una lista limitata 
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di scelte utilizzabili per assegnare al campo un valore valido. Quando un utente 
seleziona un elemento dell'elenco, il valore del campo corrispondente nel dataset 
sottostante viene modificato. 

Ad esempio, si consideri una scheda per l'immissione di ordini, i cui campi siano 
collegati alia tabella OrdersTable. OrdersTable contiene un campo CustNo che 
corrisponde al codice identificativo di un cliente, ma non contiene altra informazione 
sui clienti. La tabella Customers! able contiene, invece, un campo CustNo 
corrispondente a un ID cliente e riporta anche altre informazioni, quali l'azienda e 
l'indirizzo del cliente. Sarebbe molto pratico se la scheda degli ordini consentisse a 
un impiegato di selezionare un cliente in base al nome dell'azienda anziche mediante 
1'ID cliente quando viene creata una fattura. Un componente TDBLookupListBox, che 
visualizzi tutti i nomi delle aziende presenti in Customer sT able, permetterebbe 
all'utente di selezionare dalla lista il nome dell'azienda e di impostare correttamente 
il CustNo sul modulo d'ordine. 

Questi controlli di consultazione estraggono un elenco di elementi da visualizzare da 
una delle due sorgenti indicate: 

• Un campo di consultazione definito per un dataset. 

Per specificare le voci della casella di riepilogo utilizzando un campo di 
consultazione, il dataset al quale il controllo verra collegato deve gia definire un 
campo di consultazione. (Questo processo viene descritto in "Definizione di un 
campo di consultazione" a pagina 23-9). Per specificare il campo di consultazione 
per gli elementi della casella di riepilogo: 

1 Impostare la proprieta DataSource della casella di riepilogo al datasource del 
dataset contenente il campo di consultazione da usare. 

2 Scegliere il campo di consultazione da usare nell'elenco a comparsa della 
proprieta DataField. 

Quando si attiva una tabella associata a un controllo di consultazione, il controllo 
riconosce che il campo dati e un campo di consultazione e visualizza i valori 
appropriati tratti da quest'ultimo. 

• Un datasource secondario, un campo dati e una chiave. 

Se non e stato definito un campo di ricerca per un dataset, e possibile stabilire una 
relazione analoga utilizzando una sorgente dati secondaria, un valore di campo in 
cui cercare nella sorgente dati secondaria e un valore di campo da restituire come 
elenco di elementi. Per specificare una sorgente dati secondaria per le voci della 
casella di riepilogo: 

3 Impostare la proprieta DataSource della casella di riepilogo alia sorgente dati del 
controllo. 

4 Scegliere nell'elenco a comparsa della proprieta DataFieldun campo in cui 
inserire i valori cercati. II campo scelto non puo essere un campo di 
consultazione. 

5 Impostare la proprieta ListSource della casella di riepilogo sulla sorgente dati 
del dataset contenente il campo in cui ricercare i valori. 

6 Scegliere nell'elenco a comparsa della proprieta KeyField un campo da utilizzare 
come chiave di consultazione. L'elenco a comparsa visualizza i campi per il 
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dataset associato alia sorgente dati specificata al punto 3. II campo scelto non 
deve necessariamente appartenere a un indice ma, se vi appartiene, la ricerca 
sara ancora piu rapida. 

7 Scegliere dall'elenco a comparsa della proprieta ListFieldun campo di cui 
restituire i valori. L'elenco a comparsa visualizza i campi del dataset associato 
alia sorgente dati specificata al punto 3. 

Quando si attiva una tabella associata a un controllo di consultazione, il controllo 
riconosce che le voci del suo elenco a comparsa sono tratte da una sorgente 
secondaria e visualizza i valori appropriati tratti da quest'ultima. 

Per specificare il numero di elementi visualizzati in un controllo TDBLookupListBox in 
un determinate momento, utilizzare la proprieta RowCount. L'altezza della casella di 
riepilogo viene adattata per contenere esattamente il numero di righe specificata. 

Per specificare il numero di elementi visualizzati nella lista a discesa di 
TDBLookupComboBox, utilizzare invece la proprieta DropDownRoivs. 

E possibile anche impostare una colonna in una griglia di dati in modo che agisca 
come una casella combinata di consultazione. Per informazioni sull'operazione, 
consultare "Definizione di una colonna elenco di consultazione" a pagina 19-23. 

Gestione dei valori di campo booleani con le caselle di controllo 

TDBCheckBox e un controllo casella di controllo associata ai dati. Pud essere usato per 
impostare i valori di campi boolean di un dataset. Una scheda di fattura cliente, ad 
esempio, potrebbe avere un controllo casella di controllo che, se attivato, indica che il 
cliente non e soggetto a tassazione, e se disattivato che il cliente deve pagare la 
suddetta tassa. 

II controllo casella di controllo data-aware gestisce il proprio stato di attivo o inattivo 
confrontando il valore del campo attuale con i contenuti e le proprieta ValueChecked e 
Valuellnchecked. Se il valore del campo coincide con la proprieta ValueChecked, il 
controllo e selezionato. Altrimenti, se il campo coincide con la proprieta 
Valuellnchecked, il controllo non e selezionato. 

I valori ValueChecked e Valuellnchecked non possono essere identici. 

Impostare la proprieta ValueChecked a un valore che il controllo, se attivato, deve 
inserire nel database quando l'utente si sposta in un altro record. Per impostazione 
predefinita, questo valore e impostato a "true", ma e possibile dargli qualsiasi valore 
alfanumerico adatto alle proprie esigenze. Mentre il valore di ValueChecked e attivo, e 
anche possibile registrare un elenco di elementi separati con punto e virgola. Se 
qualche elemento del record attuale coincide con i contenuti di quel campo, la casella 
di controllo viene attivata. Si puo, ad esempio, specificare una stringa ValueChecked 
come segue: 

DBCheckBoxl->ValueChecked = " true, -Yes; On"; 

Se il campo del record attuale contiene valori di "True", "Yes" o "On" la casella di 
controllo viene attivata. II confronto del campo con le stringhe ValueChecked non fa 
differenza fra maiuscole e minuscole. Se un utente controlla una casella per la quale 
ci sono stringhe ValueChecked multiple, la prima stringa e il valore che viene 
assegnato al database. 
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Se il controllo non e attivo quando l'utente si sposta su un altro record, occorre 
impostare la proprieta Valuellnchecked al valore che il controllo dovrebbe assegnare 
al database. Per impostazione predefinita, questo valore e impostato a "False", ma e 
possibile dargli un qualsiasi valore alfanumerico adatto alle proprie esigenze. Mentre 
il valore di ValueChecked e attivo, e anche possibile registrare un elenco di elementi 
separati con punto e virgola. Se nessun elemento del record attuale coincide con i 
contenuti di quel campo, la casella di controllo risulta deselezionata. 

Una casella di controllo associata ai dati viene disattivata ogni volta che il campo del 
record attuale non contiene uno dei valori elencati nelle proprieta ValueChecked e 
Valuellnchecked. 

Se il campo a cui e associata una casella di controllo e un campo logico, la casella di 
controllo controlla sempre se i contenuti del campo sono true, e si disattiva se i 
contenuti del campo sono false. In questo caso, le stringhe immesse nelle proprieta 
ValueChecked e Valuellnchecked non hanno effetto sui campi logici. 

Restrizione dei valori del campo con controlli di opzione 

TDBRadioGroup e una versione associata ai dati di un controllo gruppo di opzioni. 
Consente di impostare il valore di un campo dati con un controllo pulsante di 
opzione, in cui esiste un numero limitato di possibili valori del campo. II gruppo di 
opzioni e composto da un pulsante per ciascuno valore che il campo puo accettare. 
Gli utenti possono impostare il valore di un campo dati selezionando il pulsante di 
opzione desiderata. 

La proprieta Items determina i pulsanti di opzione che appaiono nel gruppo. Items e 
una lista di stringhe. Per ciascuna stringa di Items, viene visualizzato un pulsante di 
opzione e ciascuna stringa appare alia destra di un pulsante di opzione sotto forma di 
etichetta del pulsante. 

Se il valore corrente di un campo associato con un gruppo di opzioni coincide con 
una delle stringhe nella proprieta Items, il relativo pulsante di opzione appare 
selezionato. Se, ad esempio, Items elenca tre stringhe, "Rosso", "Giallo" e "Blu", e il 
campo del record attivo contiene il valore "Blu", il terzo pulsante del gruppo viene 
selezionato. 

Se il campo non coincide con nessuna stringa di Items, e ancora possibile selezionare 
un pulsante di opzione a patto che il campo coincida con una stringa della proprieta 
Values. Se il campo del record attivo non coincide con nessuna stringa di Items o 
Values, non viene selezionato alcun pulsante di opzione. 

La proprieta Values puo contenere un elenco facoltativo di stringhe che possono 
essere restituite al dataset quando un utente seleziona un pulsante di opzione e 
assegna un record. Le stringhe vengono associate con i pulsanti in sequenza 
numerica. La prima stringa e associata al primo pulsante, la seconda al secondo 
pulsante e cosi via. Supponiamo, ad esempio, che Items contenga "Rosso", "Giallo" e 
"Blu", e che Values contenga "Magenta", "Giallo" e "Azzurro". Se un utente 
seleziona il pulsante identificato come "Rosso", il valore "Magenta" viene inserito nel 
database. 

Se non si forniscono stringhe di Values, quando un record viene assegnato, la stringa 
di Items di un pulsante di opzione selezionato viene inserita nel database. 
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Visualizzazione di piu record 



Talvolta potrebbe essere utile visualizzare molti record nella stessa scheda. Ad 
esempio, un'applicazione per la fatturazione potrebbe visualizzare tutti gli ordini 
fatti da un singolo cliente sulla stessa scheda. 

Per visualizzare piu record, utilizzare un controllo griglia. I controlli griglia offrono 
una vista multi campo e multi record dei dati che puo rendere l'interfaccia utente 
dell'applicazione piu accattivante ed efficace. Tali controlli sono trattati nei paragrafi 
"Visualizzazione e modifica dei dati con TDBGrid" a pagina 19-16 e "Creazione di 
una griglia contenente altri controlli associati ai dati" a pagina 19-30. 

E impossibile visualizzare piu record quando si utilizza un dataset unidirezionale. 

Si potrebbe voler progettare un'interfaccia utente che visualizzi sia i campi di un 
singolo record sia le griglie per rappresentare piu record. Esistono sono due modelli 
che combinano questi due approcci: 

• Schede master-detail: E possibile rappresentare le informazioni provenienti da 
una tabella principale e da una tabella di dettaglio includendo sia controlli per 
visualizzare un singolo campo sia controlli griglia. Ad esempio, si potrebbero 
visualizzare le informazioni relative a un singolo cliente con una griglia di 
dettaglio che visualizzi gli ordini di quel cliente. Per informazioni sul 
collegamento delle tabelle sottostanti in una scheda master-detail, consultare i 
paragrafi "Creazione di relazioni master /detail" a pagina 22-36 e "Impostazione 
di relazioni master /detail mediante parametri" a pagina 22-49. 

• Schede drill-down: In una scheda che visualizza piu record, e possibile includere 
controlli per singolo campo che visualizzano informazioni dettagliate solo dal 
record corrente. Questo approccio e particolarmente utile quando i record 
includono lunghi memo o informazioni grafiche. Man mano che l'utente scorre i 
record della griglia, il campo memo o il grafico vengono aggiornati in modo da 
rappresentare il valore del record corrente. L'impostazione di questo schema e 
molto semplice. La sincronizzazione tra le due visualizzazioni e automatica se la 
griglia e il controllo per il campo memo o per l'immagine condividono un 
datasource comune. 

Normalmente, la combinazione di questi due approcci su una singola scheda non e 
una buona idea. In tali schede risulta solitamente difficile capire per l'utente quali 
sono le relazioni che intercorrono tra i dati. 




Visualizzazione e modifica dei dati con TDBGrid 



Un controllo TDBGrid consente di visualizzare e di modificare i record da un dataset 
in un formato griglia tabellare. 
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Figura 19.1 Controllo TDBGrid 
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Questi tre fattori incidono sull'aspetto dei record visualizzati in un controllo griglia: 

• Esistenza di oggetti colonna persistente def initi per la griglia utilizzando Columns 
editor. Gli oggetti colonna persistente forniscono una grande flessibilita 
nell'impostazione dell'aspetto della griglia e dei dati. Per informazioni sull'uso di 
colonne persistenti, consul tare" Creazione di una griglia personalizzata" a 
pagina 19-18. 

• Creazione di componenti campo persistente per il dataset visualizzato nella 
griglia. Per ulteriori informazioni sulla creazione di componenti campo persistente 
usando Fields editor, consultare Capitolo 23, "Operazioni con i componenti 
campo". 

• Impostazione della proprieta ObjectView del dataset per le griglie che visualizzano 
i campi ADT e i campi array. Consultare "Visualizzazione dei campi ADT e array" 
a pagina 19-24. 

Un controllo griglia ha una proprieta Columns che e di per se un wrapper in un 
oggetto TDBGridColumns. TDBGridColumns e una raccolta di oggetti TColumn che 
rappresentano tutte le colonne di un controllo griglia.Per impostare, in fase di 
progettazione, gli attributi delle colonne, si puo ricorrere all'editor Columns, oppure 
si puo usare la proprieta Columns della griglia per accedere alle proprieta, agli eventi 
e ai metodi di TDBGridColumns in fase di esecuzione. 



Uso di un controllo griglia nel suo stato predefinito 



La proprieta State della proprieta Columns di una griglia indica se esiste l'oggetto 
colonna persistente per la griglia. Columns-> State e una proprieta di sola esecuzione 
che viene automaticamente impostata per una griglia. Lo stato predefinito e 
csDefault, che indica che non esistono oggetti colonna persistente per la griglia. In 
questo caso la visualizzazione dei dati nella griglia e determinata principalmente 
dalle proprieta dei campi nel dataset della griglia, oppure, nel caso non vi siano 
componenti campo persistenti, da un insieme predefinito di caratteristiche di 
visualizzazione. 

Quando la proprieta Columns->State di una griglia e csDefault, le colonne della griglia 
vengono generate dinamicamente dai campi visibili del dataset, e l'ordine delle 
colonne nella griglia deve corrispondere a quello dei campi del dataset. Ogni colonna 
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della griglia viene associata a un componente field. Le modifiche delle proprieta 
apportate ai componenti campo appaiono immediatamente nella griglia. 

L'uso di un controllo griglia con colonne generate dinamicamente e utile per la 
visualizzazione e la modifica del contenuto di tabelle arbitrarie selezionate in fase di 
esecuzione. Dal momento che la struttura della griglia non e definita, puo cambiare 
in modo dinamico per adattarsi ai diversi database. Una singola griglia con colonne 
generate dinamicamente puo visualizzare ora una tabella Paradox, poi il risultato di 
una query SQL quando la proprieta DataSource della griglia cambia o quando viene 
modificata la proprieta DataSet dello stesso datasource. 

E possibile cambiare l'aspetto di una colonna dinamica in fase di progettazione o di 
esecuzione, ma cio che viene di fatto modificato sono le proprieta corrispondenti del 
componente campo visualizzato nella colonna. Le proprieta delle colonne dinamiche 
esistono soltanto finche una colonna viene associata con uno specifico campo in un 
singolo dataset. Per esempio, la modifica della proprieta Width di una colonna incide 
sulla proprieta DisplayWidth del campo associato a quella colonna. Le modifiche 
apportate alle proprieta delle colonne che non si basano sulle proprieta dei campi, 
come Font, esistono solo per la durata della colonna. 

Se il dataset di una griglia e costituito da componenti campo dinamici, i campi 
vengono distrutti ogni volta che il dataset viene chiuso. Quando i componenti campo 
sono distrutti, tutte le colonne dinamiche ad essi associate vengono distrutte a loro 
volta.Se il dataset di una griglia e costituito da componenti campo persistente, i 
componenti campo continuano ad esistere anche dopo che il dataset viene chiuso, 
cosicche le colonne associate a tali campi mantengono le loro proprieta quando il 
dataset viene chiuso. 

La modifica della proprieta Columns->State di una griglia in csDefault in fase di 
esecuzione cancella tutti gli oggetti colonna della griglia (anche le colonne 
persistenti) e ricostruisce le colonne dinamiche sulla base dei campi visibili del 
dataset della griglia. 

Creazione di una griglia personalizzata 



Una griglia personalizzata e quella per il quale si definiscono oggetti colonna 
persistente che descrivono come appare una colonna e come vi vengono visualizzati i 
dati. Una griglia personalizzata consente di configurare diverse griglie in modo da 
presentare viste differenti dello stesso dataset (per esempio, ordinamenti di colonna 
diversi, opzioni di campo diverse e colori e font per le colonne differenti). Una griglia 
personalizzata, inoltre, consente agli utenti di modificare l'aspetto della griglia in 
fase di esecuzione senza influire sui campi utilizzati dalla griglia o sull'ordinamento 
dei campi del dataset. 

Le griglie personalizzate devono essere usate preferibilmente con i dataset la cui 
struttura e nota in fase di progettazione. Dal momento che esse si aspettano che nel 
dataset esistano i nomi di campo stabiliti in fase di progettazione, le griglia 
personalizzate sono poco adatte alio scorrimento di tabelle arbitrarie selezionate in 
fase di esecuzione. 
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Caratteristiche delle colonne persistenti 

Quando si creano oggetti colonna persistente per una griglia, esse vengono solo 
debolmente associate con i campi sottostanti nel dataset della griglia. I valori 
predefiniti delle proprieta delle colonne persistenti vengono derivati in modo 
dinamico da una sorgente predefinita (il campo associato o la stessa griglia) finche 
non viene assegnato un valore alia proprieta della colonna. Finche non si effettua 
questa operazione, il valore della proprieta della colonna cambia via via che cambia 
la sua sorgente predefinita. Una volta assegnato un valore alia proprieta di una 
colonna, tale valore non cambia piu anche se cambia la sua sorgente predefinita. 

Per esempio, la sorgente predefinita per il titolo di una colonna e la proprieta 
DisiplayLabel di un campo associato. Se si modifica la proprieta DisplayLabel, il titolo 
della colonna riflette immediatamente la modifica. Se si assegna una stringa ai titoli 
delle colonne, questi diventano indipendenti dalla proprieta DisplayLabel dei campi 
associati. Le modifiche successive apportate alia proprieta DisplayLabel del campo 
non incidono piu sul titolo della colonna. 

Le colonne persistenti esistono indipendentemente dai componenti campo ai quali 
sono associati. Infatti, le colonne persistenti non devono essere associate con gli 
oggetti campo. Se la proprieta FieldName di una colonna persistente e vuota, o se il 
nome del campo non corrisponde a quello di nessun campo del dataset attivo della 
griglia, la proprieta Field della colonna e NULL e la colonna viene tracciata con celle 
vuote. Se si ridefinisce il metodo predefinito per il disegno della cella, nelle celle 
vuote e possibile visualizzare informazioni personalizzate. Ad esempio, e possibile 
utilizzare una colonna vuota per visualizzare sull'ultimo record di un gruppo di 
record i valori di riepilogo del gruppo. Un'altra possibility potrebbe essere quella di 
visualizzare una bitmap o un grafico a barre che rappresenti graficamente un certo 
aspetto dei dati del record. 

E possibile associare due o piu colonne persistenti alio stesso campo di un dataset. 
Per esempio, si puo visualizzare un campo numero di parte alle estremita sinistra e 
destra di una grande griglia per consentire di trovarlo piu facilmente senza dover 
scorrere la griglia. 

Dal momento che le colonne persistenti non debbono essere associate a un campo del 
dataset, e che piu colonne possono far riferimento alio stesso campo, la proprieta 
FieldCount di una griglia personalizzata puo avere un valore inferiore o uguale a 
quello della colonna della griglia. Inoltre, si tenga presente che, se la colonna al 
momento selezionata in una griglia personalizzata non e associata a un campo, la 
proprieta SelectedField della griglia e NULL e la proprieta Selectedlndex e -1. 

Le colonne persistenti possono essere configurate per visualizzare le celle delle 
griglie come una casella combinata con un elenco a comparsa di valori di 
consultazione provenienti da un altro dataset o da un elenco statico di opzioni, o 
come un pulsante ellissi (...) in una cella su cui e possibile fare clic per attivare degli 
speciali visualizzatori di dati o delle finestre di dialogo correlate alia cella attiva. 

Creazione di colonne persistenti 

Per personalizzare l'aspetto della griglia in fase di progettazione, si deve chiamare 
l'editor Columns per creare un gruppo di oggetti colonna persistente per la griglia. In 
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fase di esecuzione, la proprieta State di una griglia con oggetti colonna persistente 
viene impostata automaticamente a csCustomized. 

Per creare colonne persistenti per un controllo griglia: 

1 Selezionare il componente griglia nella scheda. 

2 Richiamare Columns editor facendo doppio clic nell'Object Inspector sulla 
proprieta Columns della griglia. 

La casella di selezione Columns visualizza le colonne persistenti che sono state 
definite per la griglia selezionata. Quando si richiama per la prima volta l'editor 
Columns, questo elenco e vuoto in quanto la griglia e nel suo stato predefinito e 
contiene quindi solo colonne dinamiche. 

Si possono creare contemporaneamente colonne persistenti per tutti i campi di un 
dataset, oppure si possono creare singole colonne persistenti. Per creare colonne 
persistenti per tutti i campi: 

1 Fare clic destro sulla griglia per richiamare il menu contestuale e scegliere Add All 
Fields. Si noti che, se la griglia non e gia associata a un datasource, Add All Fields 
e disattivato. Prima di scegliere Add All Fields, occorre associare la griglia a un 
datasource che abbia un dataset attivo. 

2 Se la griglia contiene gia colonne persistenti, comparira un finestra di dialogo che 
chiedera se si vogliono eliminare le colonne esistenti, o se si intende aggiungere le 
nuove colonne al gruppo esistente. Se si sceglie Yes, tutte le informazioni sulle 
colonne persistenti esistenti vengono rimosse, e tutti i campi del dataset attivo 
vengono inseriti per nome di campo secondo il relativo ordine nel dataset. Se si 
sceglie No, tutte le informazioni sulle colonne persistenti esistenti vengono 
mantenute, e le informazioni sulle nuove colonne, basate sui campi aggiuntivi del 
dataset, vengono aggiunte al dataset. 

3 Fare clic su Close per applicare le colonne persistenti alia griglia e chiudere la 
finestra di dialogo. 

Per creare singole colonne persistenti: 

1 Scegliere il pulsante Add nel Columns editor. La nuova colonna verra selezionata 
nella casella di selezione. Alia nuova colonna vengono attribuiti un numero 
sequenziale e un nome predefinito (per esempio, - TColumn). 

2 Per associare un campo a questa nuova colonna, impostare la proprieta FieldName 
nell'Object Inspector. 

3 Per impostare il titolo della nuova colonna, espandere la proprieta Title nell'Object 
Inspector e impostare la proprieta Caption. 

4 Chiudere Columns editor per applicare le colonne persistenti alia griglia e 
chiudere la finestra di dialogo. 

In fase di esecuzione, e possibile passare a colonne persistenti assegnando 
csCustomized alia proprieta Columnsv.State. Tutte le colonne della griglia vengono 
distrutte e vengono costruite nuove colonne persistenti per ciascun campo del 
dataset della griglia. In esecuzione sara possibile poi aggiungere una colonna 
persistente chiamando il metodo Add della lista di colonne 
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DBGridl->Columns->Add() ; 



Cancellazione di colonne persistenti 

La cancellazione di una colonna persistente da una griglia risulta utile per eliminare i 
campi che non devono essere visualizzati. Per rimuovere una colonna persistente da 
una griglia: 

1 Fare doppio clic sulla griglia per visualizzare il Columns editor. 

2 Selezionare il campo da rimuovere nella casella di selezione Columns. 

3 Fare clic su Delete (in alternativa, per rimuovere una colonna si puo anche 
ricorrere al menu contestuale o al tasto Cane). 

Se si cancellano tutte le colonne di una griglia, la proprieta Columns->State ritorna al 
suo stato csDefault e costruisce automaticamente colonne dinamiche per ogni campo 
del dataset. 

In esecuzione e possibile cancellare una colonna persistente semplicemente liberando 
l'oggetto colonna: 

delete DBGridl->Columns->Items [5] ; 

Sistemazione dell'ordine delle colonne persistenti 

L'ordine in cui le colonne vengono visualizzate nell'editor Columns e lo stesso con 
cui appaiono nella griglia. Per cambiare tale ordine, basta trascinare e rilasciare le 
colonne all'interno della casella di selezione Columns. 

Per cambiare l'ordine di una colonna: 

1 Selezionare la colonna nella casella di selezione Columns. 

2 Trascinarla in una nuova posizione nella casella di selezione. 

E anche possibile cambiare l'ordine delle colonne facendo clic sul titolo della colonna 
e trascinandola nella nuova posizione. 

II riordinamento dei campi persistenti nel Fields editor riordina anche le colonne in 
una griglia predefinita, ma non in una griglia personalizzata. 

Non e possibile riordinare in fase di progettazione le colonne nelle griglie che 
contengono colonne e campi dinamici, dal momento che non esiste alcunche di 
persistente per registrare il campo modificato o l'ordine delle colonne. 

In fase di esecuzione, se la proprieta DragModedella griglia e impostata a dmManual, 
l'utente puo utilizzare il mouse per trascinare una colonna in una nuova posizione 
all'interno della griglia. II riordino delle colonne di una griglia, la cui proprieta State e 
impostata alio stato csDefault, riordina anche componenti campo nel dataset 
sottostante alia griglia. L'ordine dei campi nella tabella fisica resta inalterato. Per 
impedire all'utente di riordinare le colonne in fase di esecuzione, impostare la 
proprieta DragMode della griglia a dm Automatic. 

In esecuzione, lo spostamento di una colonna attiva l'evento OnColumnMoveddella 
griglia. 
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Impostazione delle proprieta di una colonna in progettazione 

Le proprieta di una colonna determinano il modo in cui i dati vengono visualizzati 
nelle relative celle. La maggior parte delle proprieta di una colonna ottiene i propri 
valori predefiniti dalle proprieta associate a un altro componente, detto sorgente 
predefinita, come ad esempio una griglia o un componente field associato 

Per impostare le proprieta di una colonna, selezionare la colonna nel Columns editor 
e impostarne le proprieta nell'Object Inspector. La tabella seguente riporta le 
proprieta fondamentali di una colonna che e possibile impostare. 

Tabella 19.2 Proprieta di Columns 
Proprieta Funzione 

Alignment Allinea a sinistra, a destra o al centro i dati del campo nella colonna. Sorgente 

predefinita: TField:: Alignment. 

ButtonStyle cbsAuto: (impostazione predefinita) Visualizza un elenco a comparsa se il 

campo associato e un campo di consultazione, o se la proprieta PickList della 
colonna contiene dati. 

cbsEllipsis: Visualizza un pulsante con puntini di sospensione (...) a destra della 
cella. Facendo clic sul pulsante, si attiva l'evento OnEditButtonClick della 
griglia. 

cbsNone: La colonna usa solo il controllo normale di editing per modificare i 
dati della colonna. 

Color Specifica il colore di sfondo delle celle della colonna. Sorgente predefinita: 

TDBGridy.Color. (Per il colore di primo piano del testo, vedere la proprieta 
Font.) 

DropDownRows Numero di righe di testo visualizzate dall'elenco a comparsa. Impostazione 
predefinita: 7. 

Expanded Specifica se la colonna e espansa. Si applica solo alle colonne che 

rappresentano campi ADT o array. 

FieldName Specifica il nome del campo associato a questa colonna. Pud essere vuoto. 

Readonly true: I dati della colonna non possono essere modificati dall'utente. 

false: (impostazione predefinita) I dati della colonna possono essere 
modificati. 

Width Specifica la larghezza della colonna in pixel sullo schermo. Sorgente 

predefinita: derivato da TFieldv.DisplayWidth. 

Font Specifica il tipo di font, le dimensioni e il colore usati per rappresentare il testo 

nella colonna. Sorgente predefinita: TDBCridv.Font. 

PickList Contiene un elenco di valori da visualizzare in un elenco a comparsa nella 

colonna. 

Title Imposta le proprieta del titolo della colonna selezionata. 
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La tabella seguente riporta le opzioni che si possono specificare per la proprieta Title. 

Tabella 19.3 Proprieta Title del TColumn espanso 
Proprieta Funzione 

Alignment Allinea a sinistra (impostazione predefinita), a destra o al centro il testo del titolo 
della colonna. 

Caption Specifica il testo da visualizzare nella colonna del titolo. Sorgente predefinita: 
TField::DisplayLabel. 

Color Specifica il colore di sfondo usato per tracciare la celle del titolo della colonna. 

Sorgente predefinita: TDBGridr.FixedColor. 

Font Specifica il tipo di font, le dimensioni e il colore usati per rappresentare il testo nella 

colonna. Sorgente predefinita: TDBGrid::TitleFont. 



Definizione di una colonna elenco di consultazione 

E possibile creare una colonna che visualizza una lista a discesa di valori, simili a un 
controllo casella combinata di consultazione. Per specificare che la colonna agisce 
come una casella combinata, impostare la proprieta ButtonStyle della colonna a 
cbsAuto. Una volta riempita la lista con valori, quando una cella di quella colonna e in 
modalita editing, la griglia visualizza automaticamente un pulsante simile a quello di 
una casella combinata a discesa. 

Esistono due modi per riempire la lista con valori selezionabili dall'utente: 

• E possibile ottenere i valori da una tabella di consultazione. Per fare in modo che 
una colonna visualizzi una lista a discesa di valori prelevati da una tabella di 
consultazione differente, e necessario definire nel dataset un campo di 
consultazione. Per informazioni sulla creazione di campi di consultazione, vedere 
il paragrafo "Definizione di un campo di consultazione" a pagina 23-9. Una volta 
definito il campo di consultazione, occorre impostare FieldName della colonna al 
nome di tale campo. La lista a comparsa viene riempita automaticamente con i 
valori di consultazione definiti tramite il campo di consultazione 

• E possibile specificare esplicitamente in progettazione una lista di valori. Per 
immettere i valori della lista in fase di progettazione, fare doppio clic nell'Object 
Inspector sulla proprieta PickListdella colonna. In questo modo viene attivato 
l'editor String List, in cui si immetteranno i valori che compongono la lista di 
scelte della colonna. 

Per impostazione predefinita, la lista a discesa visualizza 7 valori. E possibile 
modificare la lunghezza di questa lista impostando la proprieta DropDownRows. 

Per ripristinare il normale comportamento di una colonna a cui e stata assegnata una 
lista esplicita di scelte, cancellare tutto il testo dalla lista di scelte utilizzando lo String 
List editor. 



Inserimento di un pulsante in una colonna 

Una colonna puo visualizzare un pulsante ellissi (...) a destra del normale editor di 
celle. Ctrl+lnvio o un clic del mouse attivano l'evento OnEditButtonClick della griglia. Si 
puo usare il pulsante ellissi per richiamare schede contenenti viste piu dettagliate dei 
dati della colonna. Per esempio, in una tabella che visualizza prospetti di fatture, si 
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puo impostare un pulsante ellissi nella colonna Totale fattura per richiamare una 
scheda che visualizzi le voci di quella fattura, o la formula usata per il calcolo 
dell'IVA, e cosi via. Per i campi grafici si puo usare il pulsante ellissi per richiamare 
una scheda che visualizzi un'immagine 

Per creare un pulsante ellissi in una colonna: 

1 Selezionare la colonna nella casella di selezione Columns. 

2 Impostare ButtonStyle a cbsEllipsis. 

3 Scrivere un gestore di eventi OnEditButtonCHck 

Ripristino dei valori predefiniti in una colonna 

In esecuzione e possibile controllare la proprieta AssignedValues di una colonna per 
determinare se una proprieta della colonna e stata assegnata esplicitamente. I valori 
che non sono stati definiti in modo esplicito derivano dinamicamente dal campo 
associato o dalle impostazioni predefinite della griglia. 

E possibile annullare le modifiche apportate alle proprieta in una o piu colonne. E 
sufficiente selezionare nel Columns editor la colonna o le colonne da ripristinare, 
quindi selezionare Restore Defaults dal menu contestuale. Restore Defaults annulla 
le impostazioni assegnate alle proprieta e riporta le proprieta di una colonna ai valori 
derivati dal relativo componente field sottostante 

In esecuzione, e possibile reimpostare tutte le proprieta predefinite di una singola 
colonna chiamando il metodo RestoreDefaults della colonna. Chiamando il metodo 
RestoreDefaults dell'elenco di colonne, e inoltre possibile ripristinare le proprieta 
predefinite per tutte le colonne di una griglia: 

DBGridl->Columns->RestoreDef aults ( ) ; 

Visualizzazione dei campi ADT e array 



Talvolta i campi del dataset della griglia non rappresentano valori semplici come 
testo, grafica, valori numerici, e cosi via. Alcuni server di database consentono campi 
che sono un composto di tipi di dati piu semplici, come i campi ADT o campi di 
array. 

Una griglia puo visualizzare i campi compositi in due modi: 

• Puo " scomporre" il campo in modo che ognuno dei tipi piu semplici che 

costituiscono il campo appaia come un campo separato nel dataset. Quando un 
campo composito viene scomposto, i suoi costituenti vengono visualizzati come 
campi separati, e la provenienza da una sorgente comune e messa in evidenza solo 
dal fatto che ogni nome di campo e preceduto dal nome del campo genitore 
comune incluso nella tabella del database sottostante. 

Per visualizzare i campi compositi come se fossero campi separati, impostare la 
proprieta ObjectView del dataset a false. II dataset memorizza i campi compositi 
come un insieme di campi separati e la griglia si comporta di conseguenza 
assegnando a ogni singolo costituente una colonna separata. 
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• Pud visualizzare campi compositi in una singola colonna, riflettendo il fatto che 
essi sono un singolo campo. Quando i campi compositi vengono visualizzati 
utilizzando una singola colonna, la colonna pud essere espansa e compressa 
facendo clic sulla freccia presente nella barra del titolo del campo oppure 
impostando la proprieta Expanded della colonna: 

• Quando una colonna viene espansa, ogni campo figlio viene visualizzato nella 
propria sottocolonna, visualizzando, sotto la barra del titolo del campo 
genitore, una barra del titolo. La barra del titolo della griglia viene incrementata 
in altezza e riporta nella prima riga il nome del campo composito, mentre la 
seconda riga viene suddivisa tra le singole parti. La barra del titolo dei campi 
non composti risulta pertanto straordinariamente alta. Questa espansione 
continua per quei costituenti che, a loro volta, sono campi compositi (ad 
esempio, un tabella di dettaglio annidata in un'altra tabella di dettaglio), 
incrementando di conseguenza l'altezza della barra del titolo. 

• Quando il campo viene compresso, viene visualizzata solo una colonna 
contenente una stringa non modificabile, delimitata da virgole, che contiene i 
campi figlio. 

Per visualizzare un campo composito in una colonna espandibile e comprimibile, 
impostare la proprieta ObjectView del dataset a true. II dataset memorizza il campo 
composito come un singolo componente campo che contiene un insieme di 
sottocampi annidati. La griglia riflette questa impostazione visualizzando una 
colonna che puo essere espansa e compressa. 

La Figura 19.2 mostra la griglia con un campo ADT e con un campo array. La 
proprieta ObjectView del dataset e impostata a false, cosicche ogni campo figlio ha 
una colonna. 

Figura 19.2 Controllo TDBGrid con ObjectView impostato a false 
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Le Figura 19.3 e 19.4 mostrano la griglia con un campo ADT e con un campo array. La 
Figura 19.3 mostra i campi ridotti. In questo stato non e possibile modificarli. La 
Figura 19.4 mostra i campi espansi. Per espandere e per ridurre i campi, occorre farvi 
sopra clic nella barra del titolo dei campi. 
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Figura 19.3 Controllo TDBGrid con Expanded impostato a false 
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Figura 19.4 Controllo TDBGrid con Expanded impostato a true 
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La tabella seguente elenca le proprieta che incidono sul modo in cui appaiono i campi 
ADT e gli array in un TDBGrid: 

Tabella 19.4 Proprieta che influiscono sulla modalita di visualizazione dei campi compositi 



Proprieta 


Oggetto 


Funzione 


Expandable 


TColumn 


Indica se la colonna pud essere espansa in modo da mostrare i 
campi figlio in colonne separate e modificabili. (a sola lettura) 


Expanded 


TColumn 


Specifica se la colonna e espansa. 


MaxTitleRows 


TDBGrid 


Specifica il numero massimo di righe di titolo che e possibile 
visualizzare nella griglia 


Object View 


TDataSet 


Specifica se i campi sono visualizzati come "scomposti" o in 
modo oggetto, in cui ogni campo oggetto pud essere espanso e 
compresso. 


ParentColumn 


TColumn 


Fa riferimento all'oggetto TColumn a cui appartiene la colonna 
del campo figlio. 



Oltre ai campi di tipo ADT, alcuni dataset includono campi che fanno riferimento a 
un altro dataset (campi dataset) o a un record in altri campi dataset (reference). Le 
griglie data-aware visualizzano rispettivamente tali campi come "(DataSet)" o 
"(Reference)". In fase di esecuzione, alia destra di tali campi appare un pulsante con 
ellissi. Facendo clic sul pulsante con ellissi viene attivata una nuova scheda con una 
griglia che visualizza il contenuto del campo. Per i campi dataset, questa griglia 
visualizza il dataset che rappresenta il valore del campo. Per campi di riferimento, 
questa griglia contiene una singola riga che visualizza il record di un altro dataset. 



Impostazione delle opzioni per la griglia 

E possibile usare la proprieta Options della griglia in fase di progettazione per 
controllare il comportamento di base e l'aspetto della griglia in fase di esecuzione. 
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Quando un componente griglia viene collocato per la prima volta su una scheda in 
fase di progettazione, la proprieta Options nell'Object Inspector viene visualizzata 
con un segno + (piu) per indicare che la proprieta Options puo essere espansa per 
visualizzare una serie di proprieta booleane che e possibile impostare singolarmente. 
Per visualizzare e impostare queste proprieta, fare clic sul simbolo +. Sotto la 
proprieta Options, nell'Object Inspector, appare la lista delle opzioni. II simbolo + si 
trasforma nel simbolo - (meno), che consente di comprimere la lista facendo clic su di 
esso. 

La tabella seguente elenca le proprieta Options che e possibile impostare, e descrive il 
modo in cui influiscono sulla griglia in fase di esecuzione. 

Tabella 19.5 Proprieta Options espansa di TBDGrid 



Opzione 

dgEditing 



dgAlwaysShowEditor 



dgTitles 



dglndicator 



dgColumnResize 



dgColLines 



dgRowLines 



dgTabs 



dgRowSelect 



Funzione 

true: (Impostazione predefinita). Consente la modifica, rinserimento e 
la cancellazione dei record della griglia. 

false: Disabilita la modifica, l'inserimento e la cancellazione dei record 
della griglia. 

true: Quando un campo viene selezionato, e nello stato Edit. 

false: (Impostazione predefinita). Un campo non e automaticamente 
nello stato Edit quando viene selezionato. 

true: (Impostazione predefinita). Visualizza i nomi dei campi in cima 
alia griglia. 

false: Disattiva la visualizzazione dei nomi dei campi. 

true: (Impostazione predefinita). L'indicatore di colonna appare a 
sinistra della griglia, e l'indicatore del record attivo (una freccia a 
sinistra della griglia) e attivato per mostrare il record attivo. In fase di 
inserimento, la freccia diventa un asterisco. In fase di modifica, 
diventa un I-beam. 

false: L'indicatore di colonna e disattivato. 

true: (Impostazione predefinita). Le colonne possono essere 
ridimensionate trascinando i relativi righelli nell'area del titolo. II 
ridimensionamento modifica la larghezza corrispondente del 
componente TField sottostante. 

false: Le colonne non possono essere ridimensionate nella griglia. 

true: (Impostazione predefinita). Visualizza delle righe di divisione 
verticale tra le colonne. 

false: Non visualizza delle righe di divisione verticale tra le colonne. 

true: (Impostazione predefinita). Visualizza delle righe di divisione 
verticale tra i record. 

false: Non visualizza delle righe di divisione verticale tra i record. 

true: (Impostazione predefinita). Attiva lo spostamento tra i campi dei 
record. 

false: La pressione del tasto di tabulazione fa uscire dal controllo 
griglia. 

true: La barra di selezione si espande all'intera larghezza della griglia. 

false: (Impostazione predefinita). La selezione di un campo in un 
record seleziona solo quel campo. 
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Tabella 19.5 Proprieta Options espansa di TBDGrid (continua) 
Opzione Funzione 

dgAlwaysShowSelection true: (Impostazione predefinita). La barra di selezione nella griglia e 
sempre visibile, anche se il fuoco e su un altro controllo. 

false: La barra di selezione nella griglia e visibile solo quando il fuoco 
e sulla griglia. 

dgConfirmDelete true: ((Impostazione predefinita). Chiede conferma per la 

cancellazione dei record (Ctrl+Canc)). 

false: Cancella i record senza chiedere alcuna conferma. 

dgCancelOnExit true: (Default). Impostazione predefinita). Annulla un inserimento in 

sospeso quando il fuoco si sposta dalla griglia. Questa opzione 
impedisce l'invio accidentale di record parziali o vuoti. 

false: Consente gli inserimenti in sospeso. 

dgMultiSelect true: Consente all'utente di selezionare righe non contigue nella 

griglia usando i tasti Ctrl+Maiusc o Maiusc+ freccia. 

false: (Impostazione predefinita). Non consente all'utente di 
selezionare piu righe. 



Editing nella griglia 



In fase di esecuzione si puo usare una griglia per la modifica di dati esistenti o per 
1'immissione di nuovi record, se vengono soddisfatte le seguenti condizioni 
predefinite: 

• La proprieta CanModify del Dataset e true. 

• La proprieta ReadOnly della griglia e false. 

Quando un utente modifica un record nella griglia, le modifiche apportate a ciascun 
campo vengono inviate in un buffer interno per i record, ma non vengono inoltrate 
finche l'utente non si sposta in un record diverso della griglia. Anche se il fuoco si 
sposta su un altro controllo di una scheda, la griglia non inoltra le modifiche finche il 
cursore del dataset non viene spostato su un altro record. Quando un record viene 
inoltrato, il dataset controlla tutti i componenti associati ai dati collegati per verificare 
se ci sono modifiche di stato. Se sorge un problema nell'aggiornamento dei campi 
contenenti i dati modificati, la griglia solleva un'eccezione e non modifica il record. 

Se l'applicazione conserva gli aggiornamenti in cache, la conferma delle modifiche a 
un record si limita ad aggiunge tali modifiche a una cache interna. Esse non vengono 
registrare nella tabella del database sottostante finche l'applicazione non applica gli 
aggiornamenti. 

Premendo il tasto Esc in qualunque campo, si possono annullare tutte le modifiche 
apportate a un record prima di passare su un altro. 



Controllo del disegno della griglia 



II primo livello di controllo su come un controllo griglia viene disegnata e 
l'impostazione delle proprieta delle colonne. La griglia usa automaticamente le 
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proprieta del font, del colore e di allineamento di una colonna per tracciare le relative 
celle. II testo dei campi dati viene riportato usando le proprieta DisplayFormat o 
EditFormat del componente field associato alia colonna. 

E possibile potenziare tramite codice la logica predefinita di visualizzazione della 
griglia in un evento OnDrawColumnCell della griglia. Se la proprieta DefaultDrawing 
della griglia e true, il normale disegno viene eseguito prima che venga chiamato il 
gestore di evento OnDrawColumnCell. II codice puo poi intervenire sopra il piano di 
visualizzazione predefinito. Cio e particolarmente utile quando e stata definita una 
colonna persistente vuota e si vogliono tracciare particolari elementi grafici nelle celle 
di tale colonna. 

Se si intende sostituire completamente la logica di disegno della griglia, occorre 
impostare DefaultDrawing a false e collocare il codice di disegno nell'evento 
OnDrawColumnCell della griglia. Se si preferisce sostituire la logica di disegno solo in 
determinate colonne o in certi tipi di campi dati, si puo chiamare 
DefaultDrawColumnCell all'interno del gestore di evento OnDrawColumnCell per far si 
che la griglia usi il codice normale di disegno per le colonne selezionate. Cio riduce, 
per esempio, la quantita di lavoro necessaria per cambiare solo il modo in cui 
vengono tracciati i tipi di campo Boolean. 

Risposta alle azioni dell'utente in fase di esecuzione 

E possibile modificare il comportamento della griglia scrivendo dei gestori di evento 
che rispondano ad azioni specifiche all'interno della griglia in fase di esecuzione. Dal 
momento che una griglia generalmente visualizza contemporaneamente molti campi 
e record, e possibile che si abbiano esigenze molto specifiche per rispondere ai 
cambiamenti nelle singole colonne. Per esempio, si potrebbe decidere di attivare e 
disattivare un pulsante in un punto qualunque della scheda ogni volta che un utente 
entra ed esce da una determinata colonna. 

La tabella seguente elenca gli eventi di una griglia disponibili nell'Object Inspector. 
Tabella 19.6 Eventi di controllo della griglia 
Evento Funzione 

OnCellClick Si verifica quando un utente fa clic su una cella nella griglia. 

OnColEnter Si verifica quando un utente si sposta in una colonna nella griglia. 

OnColExit Si verifica quando un utente lascia una colonna nella griglia. 

OnColumnMoved Si verifica quando l'utente sposta una colonna in una nuova posizione. 

OnDblClick Si verifica quando un utente fa doppio clic nella griglia. 

OnDragDrop Si verifica quando un utente effettua un'operazione 'drag-and-drop' nella 

griglia. 

OnDragOver Si verifica quando un utente trascina sopra la griglia. 

OnDrawColumnCell Si verifica quando l'applicazione ha bisogno di disegnare singole celle. 

OnDrawDataCell (obsoleto) Si verifica quando l'applicazione ha bisogno di disegnare 
singole celle se State e csDefault. 

OnEditButtonClick Si verifica quando l'utente fa clic su un pulsante ellissi in una colonna. 

OnEndDrag Si verifica quando un utente interrompe il trascinamento nella griglia. 
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Tabella 19.6 Eventi di controllo della griglia (continua) 



Pt/antn 
CvelHU 


Ci in7inno 


OnEnter 


Si verifica quando la griglia ottiene il fuoco. 


OnExit 


Si verifica quando la griglia perde il fuoco. 


OnKeyDown 


Si verifica quando un utente preme un tasto o una combinazione di tasti 
sulla tastiera mentre si trova nella griglia. 


OnKeyPress 


Si verifica quando un utente preme un singolo tasto alfanumerico sulla 
tastiera mentre si trova nella griglia. 


OnKeyUp 


Si verifica quando un utente rilascia un tasto mentre si trova nella griglia. 


OnStartDrag 


Si verifica quando un utente inizia il trascinamento nella griglia. 


OnTitleClick 


Si verifica quando un utente fa clic sul titolo di una colonna. 



Ci sono molti usi per questi eventi. Per esempio, si potrebbe scrivere un gestore per 
l'evento OnDUClick che richiami un elenco da cui un utente possa scegliere un valore 
da inserire in una colonna. Tale gestore userebbe la proprieta SelectedField per 
determinare la riga e la colonna attive. 



Creazione di una griglia contenente altri controlli associati ai dati 



Un controllo TDBCtrlGrid visualizza piu campi in piu record in un formato griglia 
tabellare. Ogni cella della griglia mostra piu record di un'unica riga. Per usare un 
controllo griglia per database: 

1 Collocare un controllo griglia per database su una scheda. 

2 Impostare la proprieta DataSource della griglia al nome di un datasource. 

3 Collocare i singoli controlli dati all'interno della cella di progettazione per la 
griglia. La cella di progettazione e quella piu in alto o piu a sinistra nella griglia, ed 
e Tunica cella in cui si possono collocare altri controlli. 

4 Impostare la proprieta DataField per ciascun controllo dati al nome di un campo. II 
datasource per questi controlli e gia impostato a quello del controllo griglia per 
database. 

5 Sistemare i controlli all'interno della cella nel modo desiderate 

Quando si compila e si esegue un'applicazione che contiene un controllo griglia per 
database, la sistemazione dei controlli dati impostata nella cella di progettazione in 
progettazione viene riprodotta in tutte le celle della griglia. Ogni cella visualizza un 
record diverso di un dataset. 
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Figura 19.5 TDBCtrlGrid in fase di progettazione 
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La tabella seguente riporta alcune delle proprieta specifiche delle griglie controllo 
database che e possibile impostare in progettazione: 

Tabella 19.7 Proprieta del controllo griglia per database selezionato 
Proprieta Funzione 

AllowDelete true (impostazione predefinita): Permette la cancellazione dei record. 

false: Impedisce la cancellazione dei record. 
Allowlnsert true (default): impostazione predefinita): Permette l'inserimento dei record. 

false: Impedisce l'inserimento dei record. 
ColCount Imposta il numero delle colonne della griglia. Impostazione predefinita = 1. 
Orientation goVertical (impostazione predefinita): Visualizza i record dall'alto verso il basso. 

goHorizontal: Visualizza i record da sinistra a destra. 

PanelHeight Imposta l'altezza di un singolo pannello. Impostazione predefinita = 72. 

PanelWidth Imposta la larghezza di un singolo pannello. Impostazione predefinita = 200. 

RowCount Imposta il numero di pannelli da visualizzare. Impostazione predefinita = 3. 

ShowFocus true (impostazione predefinita): Visualizza un rettangolo relativo al fuoco intorno 
al pannello del record attivo in esecuzione. 

false: Non visualizza un rettangolo relativo al fuoco. 



Per ulteriori informazioni sulle proprieta e sui metodi delle griglie controllo per 
database, consultare la online VCL Reference. 



Spostamento e gestione dei record 



TDBNavigator mette a disposizione degli utenti un semplice controllo per spostarsi 
attraverso i record di un dataset e per gestirli. II 'navigatore' e costituito da una serie 
di pulsanti che consentono a un utente di spostarsi in avanti o a ritroso attraverso i 
record di un record alia volta, di andare al primo record o di passare all'ultimo, di 
inserire un nuovo record o di aggiornarne uno esistente, di inserire le modifiche ai 
dati o di annullarle, di cancellare un record o di aggiornarne la visualizzazione. 
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La Figura 19.6 mostra il navigatore che appare per impostazione predefinita quando, 
in fase di progetto, lo si colloca su una scheda. II navigatore e composto da una serie 
di pulsanti che permettono a un utente di spostarsi da un record a un altro di un 
dataset e di modificare, cancellare, inserire e assegnare record. La proprieta 
VisibleButtons del navigatore consente di nascondere o di mostrare dinamicamente 
un sottoinsieme di questi pulsanti 

Figura 19.6 Pulsanti del controllo TDBNavigator 

Inserisci record Elimina record corrente 



Record 
successivo — 

Primo record 

Record 
precedente - 



-H 



Invia modifiche record 
Aggiorna record 
Annulla modifiche record 



Ultimo record Modifica record corrente 



La tabella che segue descrive i pulsanti del navigatore. 

Tabella 19.8 Pulsanti di TDBNavigator 
Pulsante Funzione 

First Chiama il metodo First del dataset per impostare il record corrente al primo record. 

Prior Chiama il metodo Prior del dataset per impostare il record corrente al record 

precedente. 

Next Chiama il metodo Next del dataset per impostare il record corrente al record 

successivo. 

Last Chiama il metodo Last del dataset per impostare il record corrente all'ultimo record. 

Insert Chiama il metodo Insert del dataset per inserire un nuovo record prima del record 
corrente e impostare il dataset nello stato Insert. 

Delete Cancella il record attuale. Se la proprieta ConfirmDelete e true prima di cancellare 
chiede la conferma. 

Edit Pone il dataset nello stato Edit in modo da consentire la modifica del record attuale. 

Post Scrive le modifiche apportate al record corrente nel database. 

Cancel Cancella le modifiche al record corrente e riporta il dataset alio stato Browse. 

Refresh Azzera i buffer di visualizzazione dei controlli dati, quindi aggiorna i propri buffer 
dalla tabella fisica o dalla query. E utile nel caso in cui i dati associati siano stati stati 
modificati da un'altra applicazione. 



Scelta dei pulsanti del navigatore da visualizzare 



Quando, in fase di progetto, si colloca per la prima volta TDBNavigator su una 
scheda, tutti i relativi pulsanti sono visibili. Per disattivare i pulsanti che non si 
vogliono usare su una scheda, si puo usare la proprieta VisibleButtons. Ad esempio, 
quando si opera con un dataset unidirezionale, solo i pulsanti First, Next e Refresh 
sono significativi. Su una scheda nata per operazioni di consultazione anziche di 
modifica, ad esempio, si potrebbero disattivare i pulsanti Edit, Insert, Delete, Post e 
Cancel. 
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Visualizzazione e occultamento dei pulsanti del navigatore in fase di 
progettazione 

La proprieta VisibleButtons nell'Object Inspector viene visualizzata con un segno + 
per indicare che puo essere espansa per visualizzare un valore booleano per ciascun 
pulsante sul navigatore. Per vedere e impostare questi valori, fare clic sul segno +. 
L'elenco dei pulsanti che possono essere attivati o disattivati appare nell'Object 
Inspector sotto la proprieta VisibleButtons. II simbolo + (piu) si trasforma nel simbolo 
- (meno), che consente di comprimere la lista delle proprieta facendo clic su di esso. 

La visibilita del pulsante e indicata dallo stato Boolean del valore del pulsante. Se il 
valore e impostato a true, il pulsante appare nel TDBNavigator. Se e false, il pulsante 
viene rimosso dal navigatore in fase di progetto e durante l'esecuzione. 

Non appena i valori del pulsante sono impostati a false, vengono rimossi da 
TDBNavigator sulla scheda e i pulsanti che rimangono vengono espansi in ampiezza 
per riempire il controllo. E possibile trascinare le maniglie del controllo per 
ridimensionare i pulsanti. 

Visualizzazione e occultamento dei pulsanti del navigatore in fase di 
esecuzione 

In fase di esecuzione e possibile nascondere o mostrare i pulsanti del navigatore in 
risposta ad azioni dell'utente o a stati dell'applicazione. Si supponga, ad esempio, di 
fornire un singolo navigatore per spostarsi tra due dataset diversi, uno dei quali 
consente agli utenti di modificare record e l'altro e a sola lettura. Quando si passa da 
un dataset all'altro, l'utente potrebbe voler nascondere i pulsanti Insert, Delete, Edit, 
Post, Cancel e Refresh del dataset a sola lettura e mostrarli per l'altro dataset. 

Si supponga di voler impedire la modifica di OrdersTable nascondendo i pulsanti 
Insert, Delete, Edit, Post, Cancel e Refresh del navigatore, ma di volere anche permettere 
la modifica di CustomersTable. La proprieta VisibleButtons controlla quali pulsanti 
vengono visualizzati nel navigatore. Di seguito e riportato un possibile modo per 
scrivere il codice del gestore di evento: 

void __fastcall TForml: :CustomerCompanyEnter(TObject *Sender) 

{ 

if (Sender == (TObject *)CustomerCompany) 
{ 

DBNavigatorAll->DataSource = CustomerCompany->DataSource; 

DBNavigatorAll->VisibleButtons = TButtonSet ( ) « nbFirst << nbPrior << nbNext « nbLast; 

} 

else 

{ 

DBNavigatorAll->DataSource = OrderNurn->DataSource; 

DBNavigatorAll->VisibleButtons = TButtonSet () « nblnsert << nbDelete « nbEdit 

« nbPost « nbCancel « nbRefresh; 

} 

} 
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Visualizzazione del fumetto guida 



Per visualizzare in esecuzione il fumetto guida per ciascun pulsante del navigatore, 
impostare la proprieta ShowHint del navigatore a true. Quando ShowHint e true, il 
navigatore visualizza una miniguida di suggerimento ogni volta che si passa il 
cursore del mouse sui pulsanti del navigatore. Per impostazione predefinita 
ShowHint e false. 

La proprieta Hints controlla il testo del fumetto guida per ciascun pulsante. Per 
impostazione predefinita, Hints e una lista di stringhe vuota. Quando Hints e vuota, 
ogni pulsante del navigatore visualizza il testo guida predefinito. Per fornire un 
fumetto guida personalizzato per i pulsanti del navigatore, usare lo String editor per 
registrare nella proprieta Hints una riga separata di testo per il suggerimento 
associato a ciascun pulsante. Se presenti, le stringhe create sovrascrivono i 
suggerimenti predefiniti forniti dal controllo navigatore. 

Uso di un singolo navigatore per piu dataset 



Come avviene per gli altri controlli data-aware, la proprieta DataSource di un 
navigatore specifica il datasource che collega il controllo a un dataset. Modificando 
la proprieta DataSource di un navigatore in esecuzione, un singolo navigatore puo 
consentire lo spostamento tra i record e la gestione di piu dataset. 

Si supponga che una scheda contenga due controlli di modifica collegati 
rispettivamente ai dataset Customers! able e OrdersTable tramite le sorgenti dati 
Customer sSource e OrdersSource. Quando un utente seleziona il controllo di modifica 
connesso a CustomersSource, anche il navigatore dovrebbe usare Customers Source e 
quando l'utente seleziona il controllo di modifica connesso a OrdersSource, anche il 
navigatore dovrebbe passare a OrdersSource. E possibile programmare il gestore di 
evento OnEnter di uno dei controlli di modifica e quindi condividere quell'evento 
con l'altro controllo di modifica. Per esempio: 

void __fastcall TForml: :CustomerCompanyEnter(TObject *Sender) 
{ 

if (Sender == (TObject *) CustomerCompany) 

DBNavigatorAll->DataSource = CustomerCompany->DataSource; 
else 

DBNavigatorAll->DataSource = OrderNurn->DataSource; 

} 
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Uso dei componenti 



di supporto 
decisionale 



I componenti di supporto decisionale aiutano a creare tabelle incrociate - dette anche 
crosstab - e grafici. E possibile quindi usare queste tabelle e grafici per vedere e 
riassumere i dati da prospettive diverse. Per maggiori informazioni sui dati 
incrociati, consultare "I crosstab" a pagina 20-2. 



I componenti di supporto decisionale appaiono sulla pagina Decision Cube della 
tavolozza Component: 

• II cubo decisionale, TDecisionCube, e un magazzino dati multidimensionale. 

• La sorgente decisionale, TDecisionSource, definisce lo stato del pivot attivo di una 
griglia o di un grafico decisionale. 

• La query decisionale, TDecisionQuery ; e una forma specializzata di TQuery usata 
per definire i dati in un cubo decisionale. 

• II pivot decisionale, TDecisionPivot, consente di ingrandire o di rimpicciolire le 
dimensioni del cubo decisionale o i campi con la semplice pressione di pulsanti. 

• La griglia decisionale, TDecisionGrid, mostra dati mono e multidimensionali in 
forma tabellare. 

• II grafico decisionale, TDecisionGraph, mostra i campi di una griglia decisionale 
come un grafico dinamico che cambia al variare delle dimensioni dei dati. 

La Figura 20.1 mostra tutti i componenti di supporto decisionale collocati su una 
scheda in fase di progettazione. 



Panoramica 
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I crosstab 



Figura 20.1 Componenti di supporto decisionale in progettazione 
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I crosstab 



Le tabelle incrociate, o crosstab, sono un modo di presentare sottoinsiemi di dati per 
rendere piu evidenti relazioni e andamenti. I campi della tabella diventano le 
dimensioni del crosstab mentre i valori dei campi definiscono le categorie e i 
riepiloghi all'interno di una dimensione. 

E possibile usare i componenti di supporto decisionale per disporre sulle schede i 
crosstab. TDecisionGrid mostra i dati in una tabella, mentre TDecisionGraph la traccia 
graficamente. TDecisionPivot dispone di pulsanti che semplificano la visualizzazione 

l'occultamento delle dimensioni e il loro spostamento tra le colonne e le righe. 

1 crosstab possono essere monodimensionali o multidimensionali. 
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Crosstab monodimensionali 



I crosstab monodimensionali mostrano una riga (o una colonna) di riepilogo per le 
categorie di una singola dimensione. Ad esempio, se la dimensione della colonna 
scelta e Payment e la categoria di riepilogo e Amount Paid, il crosstab in Figura 20.2 
mostra l'importo pagato con ciascuno dei metodi. 

Figura 20.2 Un crosstab mono-dimensionale 
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Crosstab multidimensionali 



I crosstab multidimensionali usano dimensioni supplementari per le righe e/o per le 
colonne. Per esempio, un crosstab bidimensionale puo mostrare gli importi pagati in 
base al metodo di pagamento per ciascun paese. 

Un crosstab tridimensionale puo mostrare gli importi pagati in base al metodo e alle 
condizioni di pagamento paese per paese, come mostrato nella Figura 20.3. 

Figura 20.3 Crosstab tridimensionale 
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Regole generali per I'uso dei componenti di supporto decisionale 



I componenti di supporto decisionale, elencati a pagina 20-l,possono essere usati 
contemporaneamente per presentare dati multidimensionali sotto forma di tabelle e 
di grafici. Ad ogni dataset possono essere collegati piu tabelle o grafici. In esecuzione, 
e possibile usare piu istanze di TDecisionPivot per visualizzare dati di prospettive 
differenti. 

Per creare una scheda con tabelle e grafici di dati multidimensionali, procedere nel 
modo seguente: 

1 Creare una scheda. 
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2 Aggiungere questi componenti alia scheda (usando poi l'Object Inspector per 
collegarli come indicato di seguito): 

• Un dataset, di solito TDecisionQuery (per maggiori informazioni, consultare 
"Creazione di dataset decisionali con l'editor Decision Query" a pagina 20-6) o 
TQuery 

• Un cubo decisionale, TDecisionCube, collegato al dataset impostando la 
proprieta DataSet al nome del dataset 

• Una sorgente decisionale, TDecisionSource, collegato al cubo decisionale 
impostando la proprieta di DecisionCube al nome del cubo decisionale 

3 Aggiungere un pivot decisionale, TDecisionPivot, e collegarlo alia sorgente 
decisionale con l'Object Inspector impostando la proprieta DecisionSource al nome 
della sorgente decisionale appropriata. II pivot decisionale e facoltativo ma utile; 
permette alio sviluppatore e agli utenti finali della scheda di modificare le 
dimensioni visualizzate in griglie o in grafici decisionali con la semplice pressione 
di pulsanti. 

Nel loro orientamento predefinito, quello orizzontale, i pulsanti sul lato sinistra 
del pivot decisionale agiscono sui campi posti sul lato sinistra della griglia 
decisionale (le righe); i pulsanti sul lato destro agiscono sui campi della parte 
superiore della griglia decisionale (le colonne). 

E possibile determinare dove fare apparire i pulsanti del pivot decisionale 
impostando la proprieta GroupLayout a xtVertical, xtLeftTop o xtHorizontal 
(impostazione predefinita). Per maggiori informazioni sulle proprieta del pivot 
decisionale, consultare "Uso dei pivot decisionali" a pagina 20-10. 

4 Aggiungere una o piu griglie e grafici decisionali, collegandoli alia sorgente 
decisionale. Per maggiori informazioni, consultare "Creazione e uso delle griglie 
decisionali" a pagina 20-11 e "Creazione e uso dei grafici decisionali" a 
pagina 20-13. 

5 Usare l'editor della query decisionale o la proprieta SQL di TDecisionQuery (o di 
TQuery) per specificare le tabelle, i campi e i riepiloghi da visualizzare nella 
griglia o nel grafico. L'ultimo campo dell'istruzione SQL SELECT deve essere il 
campo di riepilogo. Gli altri campi nell'istruzione SELECT devono essere i campi 
di GROUP BY. Per istruzioni, consultare "Creazione di dataset decisionali con 
l'editor Decision Query" a pagina 20-6. 

6 Impostare la proprieta Active della query decisionale (o del componente dataset 
alternativo) a true. 

7 Usare la griglia e il grafico decisionali per mostrare e tracciare sotto forma di 
grafico dimensioni dati differenti. Per istruzioni e suggerimenti, consultare "Uso 
delle griglie decisionali" a pagina 20-11 e "Uso dei grafici decisionali" a 
pagina 20-14. 

Per vedere un'illustrazione che riporti in una scheda tutti i componenti di supporto 
decisionale, consultare Figura 20.1 a pagina 20-2. 
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Uso dei dataset con i componenti di supporto decisionale 



L'unico componente di supporto decisionale collegato direttamente a un dataset e il 
cubo decisionale, TDecisionCube. TDecisionCube si aspetta ricevere i dati tramite i 
gruppi e i riepiloghi definiti da un'istruzione SQL di un formato accettabile. La frase 
GROUP BY deve contenere gli stessi campi non riepilogati (e nello stesso ordine) 
contenuti nella frase SELECT, e i campi di riepilogo devono essere identificati. 

II componente query decisionale, TDecisionQuery, e una versione specializzata di 
TQuery. E possibile usare TDecisionQuery per definire piu semplicemente la 
configurazione delle dimensioni (righe e colonne) e i valori di riepilogo usati per 
fornire i dati ai cubi decisionali, TDecisionCube. Come dataset per TDecisionCube un e 
possibile anche usare un comune TQuery o altri dataset abilitati a BDE, ma la corretta 
configurazione del dataset e di TDecisionCube sono di competenza del progettista. 

Per operare correttamente col cubo decisionale, tutti i campi progettati nel dataset 
devono essere dimensioni o riepiloghi. I riepiloghi devono essere valori aggiuntivi 
(come somma o conteggio) e devono rappresentare i totali per ciascuna 
combinazione dei valori di dimensione. Per semplificare al massimo la 
configurazione, nel dataset le somme devono essere chiamate "Sum..." mentre i 
conteggi dovrebbero essere chiamati "Count...". 

Decision Cube puo calcolare correttamente pivot, totali parziali e in dettaglio solo per 
i riepiloghi le cui celle sono di tipo additivo. (SUM e COUNT sono celle additive, 
AVERAGE, MAX e MIN no). La crosstab di costruzione del pivot visualizza solo le 
griglie che contengono totali additivi. Se si usano totali non additivi, ricorrere ad una 
griglia decisionale statica che non sia pivot, dettaglio o totale parziale. 

Poiche le medie possono essere calcolate usando SUM diviso per COUNT, viene 
aggiunta automaticamente una media pivot quando le dimensioni SUM e COUNT 
per un campo vengono incluse nel dataset. Questo tipo di media deve essere 
utilizzato preferibilmente per una media calcolata usando un'istruzione AVERAGE. 

Le medie possono essere calcolate anche usando COUNT(*). A questo scopo, 
includere un selettore "COUNT(*) COUNTALL" nella query. Se per calcolare le 
medie si usa COUNT(*), il singolo aggregatore puo essere usato per tutti i campi. 
COUNT(*) deve essere utilizzato solo nei casi in cui nessuno dei campi che deve 
essere riepilogato include valori vuoti, o in cui non e disponibile un totale COUNT 
per ogni campo. 

Creazione di dataset decisionali con TQuery o TTable 



Se si usa come dataset decisionale un comune componente TQuery, si deve preparare 
manualmente l'istruzione SQL, facendo attenzione a fornire una frase GROUP BY 
che contenga gli stessi campi (e nello stesso ordine) della frase SELECT. 

L'istruzione SQL puo essere simile a questa: 

SELECT ORDERS . "Terms 11 , ORDERS . "ShipVIA" , 

ORDERS. "PaymentMethod", SUM( ORDERS . "MountPaid" ) 
FROM " ORDERS. DB 11 ORDERS 

GROUP BY ORDERS." Terms", ORDERS . "ShipVIA" , ORDERS ." PaymentMethod" 
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L'ordinamento dei campi SELECT deve coincidere con quello di GROUP BY. 

Con TTable occorre dire al cubo decisionale quali sono i campi della query da 
considerare campi di raggruppamento e quali quelli da considerare campi di 
riepilogo. Per eseguire questa operazione, compilare Dimension Type per ciascun 
campo in DimensionMap della pagina Decision Cube. Occorre indicare se ciascun 
campo e una dimensione o un riepilogo, e se un riepilogo, si deve fornirne il tipo. 
Poiche le medie pivot dipendono dai calcoli SUM/ COUNT, occorre fornire anche il 
nome base del campo per consentire al cubo decisionale di confrontare le coppie di 
aggregatori SUM e COUNT. 

Creazione di dataset decisionali con I'editor Decision Query 



Tutti i dati usati dai componenti di supporto decisionale passano attraverso il cubo 
decisionale che accetta un dataset formattato in modo particolare, prodotto molto 
facilmente da una query SQL. Per maggiori informazioni, consul tare "Uso dei dataset 
con i componenti di supporto decisionale" a pagina 20-5. 

Anche se e possibile usare TTable e TQuery come dataset decisionali, risulta piu 
semplice ricorrere a TDecisionQuery, I'editor della query decisionale fornito insieme 
al prodotto. Pud essere usato per specificare tabelle, campi e riepiloghi che devono 
apparire nel cubo decisionale contribuendo a configurare correttamente le porzioni 
SELECT e GROUP BY della query SQL. 

Per usare I'editor Decision Query: 

1 Selezionare il componente della query decisionale sulla scheda, poi fare clic col 
tasto destro e scegliere Decision Query editor. Apparira la finestra di dialogo 
Decision Query editor. 

2 Selezionare il database da utilizzare. 

3 Per query su una singola tabella, fare clic sul pulsante Select Table. 

Per query piu complesse, che coinvolgono join su piu tabelle, fare clic sul pulsante 
Query Builder per visualizzare SQL Builder oppure, nella pagina SQL, scrivere 
l'istruzione SQL utilizzando la casella di testo apposita. 

4 Ritornare alia finestra di dialogo Decision Query editor. 

5 Nella finestra di dialogo Decision Query editor selezionare i campi nell'elenco 
Available Fields e assegnarli a Dimensions o a Summaries facendo clic sul 
pulsante freccia a destra opportune Mano mano che si aggiungono i campi 
all'elenco Summaries, selezionare dai menu visualizzato il tipo di riepilogo da 
utilizzare: somma, conteggio o media. 

6 Per impostazione predefinita, tutti i campi e i riepiloghi definiti nella proprieta 
SQL della query decisionale appaiono nelle caselle di riepilogo Active Dimensions 
e Active Summaries. Per eliminare una dimensione o riepilogo, selezionarlo 
nell'elenco e fare clic sulla freccia sinistra accanto all'elenco, o fare doppio clic 
sull'elemento da eliminare. Per aggiungerlo all'elenco originale, selezionarlo nella 
casella di riepilogo Available Fields e fare clic sulla freccia destra opportuna. 
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Una volta definiti i contenuti del cubo decisionale, e possibile modificare 
ulteriormente le dimensioni di visualizzazione agendo sulla proprieta DimensionMap 
e sui pulsanti di TDecisionPivot. Per maggiori informazioni, consultare le sezioni 
successive "Uso dei cubi decisionali", "Uso delle sorgenti decisionali" a pagina 20-9, 
e "Uso dei pivot decisionali" a pagina 20-10. 

Quando si usa l'editor Decision Query, la query inizialmente viene gestita nella 
sintassi SQL ANSI-92, quindi tradotta (se necessario) nel dialetto usato dal server. 
L'editor Decision Query legge e visualizza solo il formato SQL ANSI standard. La 
traduzione del dialetto viene assegnata automaticamente alia proprieta SQL di 
TDecisionQuery. Per modificare una query, effettuare l'editing della versione ANSI-92 
in Decision Query anziche nella proprieta SQL. 

Uso dei cubi decisionali 



II componente cubo decisionale, TDecisionCube, e un'area di memorizzazione dati 
multidimensionale che recupera i dati da un dataset (di solito usando un'istruzione 
SQL, strutturata in modo particolare, immessa con TDecisionQuery o TQuery). I dati 
sono memorizzati in un formato che ne semplifica l'utilizzo come pivot (ovvero, 
modifica il modo in cui i dati vengono organizzati e riepilogati) senza dover eseguire 
la query una seconda volta. 

Proprieta del cubo decisionale e eventi 



Le proprieta DimensionMap di TDecisionCube non solo controllano quali dimensioni e 
riepiloghi far apparire, ma consentono anche di impostare gli intervalli di dati e di 
specificare il numero massimo di dimensioni che il cubo decisionale puo supportare. 
Si puo anche indicare se visualizzare o meno i dati in fase di progetto. E possibile 
visualizzare nomi (le categorie), valori, totali parziali o dati. La visualizzazione dei 
dati in fase di progetto puo essere dispendiosa in termini di tempo, a seconda della 
sorgente dati utilizzata. 

Facendo clic sul pulsante con le ellissi accanto a DimensionMap nell'Object Inspector, 
appare la finestra di dialogo Decision Cube editor. E possibile usarne le pagine e i 
controlli per impostare le proprieta di DimensionMap. 

L'evento OnRefresh viene attivato ogni qualvolta si rigenera la cache del cubo 
decisionale. Gli sviluppatori possono accedere alia nuova mappa della dimensione e 
modificarla per liberare memoria, modificare il valore massimo dei riepiloghi o delle 
dimensioni, e cosi via. OnRefresh e anche utile se gli utenti accedono all'editor del 
cubo decisionale; in questa fase il codice dell'applicazione puo rispondere alle 
modifiche apportate dall'utente. 

Uso di Decision Cube editor 



E possibile usare l'editor del cubo decisionale per impostare le proprieta di 
DimensionMap dei cubi decisionali. L'editor del cubo decisionale puo essere 
visualizzato tramite l'Object Inspector, come descritto nella sezione precedente, o 
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facendo clic, in fase di progetto, con il tasto destro su un cubo decisionale in una 
scheda e selezionando Decision Cube editor. 

La finestra di dialogo Decision Cube Editor ha due separatori: 

• Dimension Settings, usato per attivare o disattivare le dimensioni disponibili, 
cambiare il nome e riformattare le dimensioni, mettere le dimensioni in un stato 
permanentemente espanso e impostare gli intervalli dati da visualizzare. 

• Memory Control, usato per impostare il massimo numero di dimensioni e 
riepiloghi che possono essere contemporaneamente attivi, per visualizzare 
informazioni sull'uso della memoria, e per determinare i nomi e i dati che 
appaiono in fase di progetto. 

Visualizzazione e modifica delle impostazioni delle dimensioni 

Per vedere le impostazioni delle dimensioni, visualizzare l'editor Decision Cube e 
fare clic sul separatore Dimension Settings. Quindi, selezionare una dimensione o un 
riepilogo nell'elenco Available Fields. Le informazioni appaiono nelle caselle sul lato 
destro dell'editor: 

• Per modificare la dimensione o il nome del riepilogo che appaiono nel pivot, nella 
griglia o nel grafico decisionali, immettere un nuovo nome nella casella di testo 
Display Name. 

• Per determinare se il campo selezionato e una dimensione o un riepilogo, leggere 
il testo nella casella di testo Type.Se il dataset e un componente TTable, e possibile 
usare Type per specificare se il campo selezionato e una dimensione o un 
riepilogo. 

• Per disattivare o attivare la dimensione o il riepilogo selezionati, modificare 
l'impostazione nella casella di riepilogo a discesa Active Type: Active, As Needed 
o Inactive. La disattivazione di una dimensione o l'uso dell'impostazione As 
Needed fanno risparmiare memoria. 

• Per modificare il formato di quella dimensione o quel riepilogo, immettere una 
stringa di formato nella casella di testo Format. 

• Per visualizzare quella dimensione o quel riepilogo per Anno, Trimestre o Mese 
(Year, Quarter, o Month), modificare l'impostazione nella casella di riepilogo a 
discesa Binning. Per mettere la dimensione o il riepilogo selezionati in uno stato 
permanentemente compresso, si puo scegliere l'opzione Set nella casella di 
riepilogo Binning. Cio puo essere utile per risparmiare memoria quando una 
dimensione ha molti valori. Per maggiori informazioni, consultaree "Componenti 
di supporto decisionale e controllo della memoria" a pagina 20-20. 

• Per determinare i valori iniziali degli intervalli, o il valore drill-down per una 
dimensione "Set", scegliere innanzi tutto l'appropriato valore Grouping 
nell'elenco a discesa Grouping, quindi immettere il valore iniziale dell'intervallo o 
il valore drill-down permanente nell'elenco a discesa Initial Value. 

Impostazione del numero massimo di dimensioni e di riepiloghi disponibili 

Per determinare il numero massimo di dimensioni e di riepiloghi disponibili per i 
pivot, le griglie e i grafici decisionali associati al cubo decisionale selezionato, 
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visualizzare l'editor Decision Cube e fare clic sul separatore Memory Control. Usare i 
controlli di modifica per regolare, se necessario, le impostazioni attive. Queste 
aiutano a controllare la quantita di memoria necessaria per il cubo decisionale. Per 
maggiori informazioni, consultare "Componenti di supporto decisionale e controllo 
della memoria" a pagina 20-20. 

Visualizzazione e modifica delle opzioni di progetto 

Per determinare quante informazioni appaiono in fase di progetto, visualizzare il 
Decision Cube editor e fare clic sul separatore Memory Control. Quindi, controllare 
l'impostazione che indica quali nomi e dati visualizzare. La visualizzazione dei dati o 
dei nomi di campo in fase di progetto puo causare a volte un degrado delle 
prestazioni dovuto al tempo necessario per recuperare i dati. 

Uso delle sorgenti decisionali 



II componente sorgente decisionale, TDecisionSource, definisce lo stato attuale del 
pivot di griglie o di grafici decisionali. Qualunque coppia di oggetti che usa la stessa 
sorgente decisionale condivide anche gli stati del pivot. 

Proprieta ed eventi 



Di seguito sono elencate alcune proprieta ed eventi particolari che controllano 
l'aspetto e il comportamento delle sorgenti decisionali: 

• La proprieta ControlType di TDecisionSource indica se i pulsanti del pivot 
decisionale devono agire come caselle di controllo (selezioni multiple) o come 
pulsanti di opzione (selezioni mutuamente esclusive). 

• Le proprieta SparseCols e SparseRows di TDecisionSource indicano se visualizzare o 
meno le colonne o le righe senza valori; se true, vengono visualizzate le colonne o 
le righe rade. 

• TDecisionSource ha i seguenti eventi: 

• OnLayoutChange si verifica quando l'utente esegue rotazioni o compressioni che 
riorganizzano i dati. 

• OnNewDimensions si verifica quando i dati vengono completamente modificati, 
come, ad esempio, quando vengono alterati i campi di riepilogo o delle 
dimensioni. 

• OnSummaryChange si verifica quando viene modificato il riepilogo attuale. 

• OnStateChange si verifica quando si attiva o si disattiva Decision Cube. 

• OnBeforePivot si verifica quando le modifiche sono gia state confermate ma 
l'interfaccia utente non e stata ancora aggiornata. Gli sviluppatori hanno 
l'opportunita di apportare modifiche, per esempio, alia capacita o alio stato di 
pivot, prima che gli utenti dell'applicazione vedano il risultato delle azioni 
precedenti. 
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• OnAfterPivot si attiva dopo una modifica nello stato di pivot. In quel preciso 
momento, gli sviluppatori possono intercettare informazioni. 

Uso dei pivot decisionali 



II componente pivot decisionale, TDecisionPivot, consente di aprire o di chiudere le 
dimensioni del cubo decisionale o i campi premendo dei pulsanti. Quando si apre 
una riga o una colonna premendo uno dei pulsanti di TDecisionPivot, la dimensione 
corrispondente appare sul componente TDecisionGrid o TDecisionGraph. Quando si 
chiude una dimensione, i dati particolareggiati non appaiono; la vista viene ridotta 
mostrando solo i totali delle altre dimensioni. Una dimensione puo essere anche in 
uno stato compresso, in cui appaiono solamente i riepiloghi per un determinato 
valore del campo dimensione. 

E inoltre possibile usare il pivot decisionale per riorganizzare le dimensioni 
visualizzate nella griglia decisionale e nel grafico decisionale. E sufficiente trascinare 
un pulsante suU'area della riga o della colonna o riordinare i pulsanti all'interno della 
stessa area. 

Per le illustrazioni dei pivot decisionali in progettazione consultare le Figure 20.1, 
20.2, e 20.3. 

Proprieta dei pivot decisionali 



Di seguito sono elencate alcune proprieta speciali che controllano l'aspetto e il 
comportamento dei pivot decisionali: 

• Le prime proprieta elencate per TDecisionPivot ne definiscono il comportamento 
complessivo e l'aspetto. E possibile impostare ButtonAutoSize a false per fare in 
modo che TDecisionPivot impedisca l'espansione e la contrazione dei pulsanti 
mentre si sta modificando la dimensione del componente. 

• La proprieta Groups di TDecisionPivot definisce quali pulsanti di dimensione 
dovranno apparire. E possibile visualizzare la riga, la colonna e i gruppi di 
pulsanti di selezione di riepilogo in qualsiasi combinazione. Si deve tenere 
presente che se si vuole maggior flessibilita sul posizionamento di questi gruppi, e 
possibile collocare in una posizione della scheda un componente TDecisionPivot 
che contiene solamente righe, e, in un'altra posizione, un secondo componente che 
contiene solamente colonne. 

• Solitamente, TDecisionPivo viene aggiunto sopra a TDecisionGrid. In base 
all'orientamento predefinito, quello orizzontale, i pulsanti sul lato sinistra di 
TDecisionPivot agiscono sui campi posti sul lato sinistra di TDecisionGrid (le righe); 
i pulsanti sul lato destro agiscono sui campi posti nella parte superiore di 
TDecisionGrid (le colonne). 

• E possibile determinare il punto in cui appaiono i pulsanti di TDecisionPivot 
impostandone la proprieta GroupLayout a xtVertical, xtLeftTop, o xtHorizontal (che e 
il valore predefinito ed e descritto nel paragrafo precedente). 
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Creazione e uso delle griglie decisionali 



I componenti della griglia decisionale, TDecisionGrid, presentano i dati incrociati 
sotto forma di tabella. Queste tabelle, descritte a pagina 20-2, vengono anche 
chiamate crosstab. La Figura 20.1 a pagina 20-2 mostra una griglia decisionale su una 
scheda in progettazione. 

Creazione di griglie decisionali 



Per creare una scheda con uno o piu tabelle di dati incrociati: 

1 Seguire le istruzioni da 1 a 3 elencate nella sezione "Regole generali per l'uso dei 
componenti di supporto decisionale" a pagina 20-3. 

2 Aggiungere uno o piu componenti TDecisionGrid (griglia decisionale) e collegarli 
alia sorgente decisionale, TDecisionSource, con l'Object Inspector impostando la 
proprieta DecisionSource al componente sorgente decisionale opportuno. 

3 Procedere con le istruzioni da 5 a 7 elencate nella sezione "Regole generali per 
l'uso dei componenti di supporto decisionale". 

Per una descrizione di cio che appare nella griglia decisionale e sul modo di 
utilizzarla, consultare la sezione "Uso delle griglie decisionali" a pagina 20-11. 

Per aggiungere un grafico alia scheda, seguire le istruzioni riportate nella sezione 
"Creazione di grafici decisionali" a pagina 20-14. 

Uso delle griglie decisionali 



II componente griglia decisionale, TDecisionGrid, visualizza i dati provenienti dai 
cubi decisionali (TDecisionCube) collegati a sorgenti decisionali (TDecisionSource). 

Per impostazione predefinita, la griglia appare con i campi dimensione disposti sul 
lato sinistra e/o superiore, a seconda delle istruzioni di raggruppamento definite nel 
dataset. Le categorie, una per ciascun valore dei dati, appaiono sotto ciascun campo. 
E possibile 

• Aprire e chiudere le dimensioni 

• Riorganizzare o ruotare righe e colonne 

• Espandere una riga per avere altri dettagli 

• Limitare la selezione della dimensione a una singola dimensione per ciascun asse 

Per maggiori informazioni sulle proprieta speciali e sugli eventi della griglia 
decisionale, consultare la sezione "Proprieta della griglia decisionale" a pagina 20-12. 

Apertura e chiusura dei campi della griglia decisionale 

Se in una dimensione o in un campo di riepilogo appare il segno piu (+), significa che 
uno o piu campi alia sua destra sono chiusi (nascosti). E possibile aprire campi e 
categorie supplementari facendo clic sul segno. II segno meno (-) indica un campo 
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completamente aperto (espanso). Quando si fa clic sul segno, il campo si chiude. 
Questa opzione puo essere disattivata; per maggiori informazioni, consultare il 
paragrafo "Proprieta della griglia decisionale" a pagina 20-12. 

Riorganizzazione di righe e colonne in griglie decisionali 

E possibile trascinare le intestazioni di riga e di colonna in nuove posizioni all'interno 
dello stesso asse osuun altro asse. In questo modo e possibile riorganizzare la griglia 
e vedere i dati da nuove prospettive man mano che cambia la modalita di 
raggruppamento. Questa opzione puo essere disattivata; per maggiori informazioni, 
consultare il paragrafo "Proprieta della griglia decisionale" a pagina 20-12. 

Se si include un pivot decisionale, e possibile premere e trascinare i pulsanti per 
riorganizzare la visualizzazione. Per istruzioni, consultare "Uso dei pivot 
decisionali" a pagina 20-10. 

Espansione dei dettagli nelle griglie decisionali 

E possibile espandere una dimensione per vedere piu dettagli. 

Ad esempio, se si fa clic col tasto destro su un'etichetta di categoria (intestazione di 
riga) per una dimensione mentre ce ne sono altre sotto di essa in forma contratta, e 
possibile decidere se espandere e consultare solamente i dati di quella categoria. Se 
una dimensione e espansa, sulla griglia non appaiono le etichette di categoria della 
dimensione, dato che vengono visualizzati solamente i record per un singolo valore 
della categoria. Se sulla scheda c'e un pivot decisionale, questo visualizza i valori di 
categoria e, volendo, consente di passare ad altri valori. 

Per espandere una dimensione: 

• Fare clic col tasto destro su un'etichetta di categoria e selezionare Drill In To This 
Value, oppure 

• Fare clic col tasto destro su un pulsante pivot e scegliere Drilled In. 
Per riattivare di nuovo la dimensione completa: 

• Fare clic col tasto destro sul pulsante pivot corrispondente, oppure fare clic col 
tasto destro nell'angolo superiore-sinistro della griglia decisionale e selezionare la 
dimensione. 

Limitazione della selezione delle dimensioni in griglie decisionali 

Modificando la proprieta ControlType della sorgente decisionale si determina se e 
possibile selezionare piu dimensioni per ciascun asse della griglia. Per maggiori 
informazioni, consultare "Uso delle sorgenti decisionali" a pagina 20-9. 

Proprieta della griglia decisionale 



II componente griglia decisionale, TDecisionGrid, visualizza i dati provenienti dal 
componente TDecisionCube collegato a TDecisionSource. Per impostazione predefinita, 
i dati appaiono in una griglia con i campi di categoria disposti sul lato sinistra e nella 
parte superiore della griglia. 



20-12 Guida alia programmazione 



Creazione e uso dei grafici decisionali 



Di seguito sono elencate alcune proprieta speciali che controllano l'aspetto e il 
comportamento delle griglie decisionali: 

• TDecisionGrid ha proprieta uniche per ciascuna dimensione.Per impostarle, 
scegliere Dimensions nell'Object Inspector, e selezionare poi una dimensione. A 
questo punto, le proprieta di quella dimensione appaiono nell'Object Inspector: 
Alignment definisce l'allineamento delle etichette di categoria per quella 
dimensione, Caption puo essere usata per sostituire il nome predefinito della 
dimensione, Color definisce il colore delle etichette di categoria, FieldName 
visualizza il nome della dimensione attiva, Format puo memorizzare qualsiasi 
formato standard per quel tipo di dati e Subtotals indica se visualizzare o meno i 
totali parziali per quella dimensione. Con i campi di riepilogo queste stesse 
proprieta vengono usate per modificare l'aspetto dei dati che appaiono nell'area di 
riepilogo della griglia. Una volta completata l'impostazione delle proprieta della 
dimensione, fare clic su un componente nella scheda o scegliere un componente 
nella casella di riepilogo a discesa nella parte superiore dell'Object Inspector. 

• La proprieta Options di TDecisionGrid consente di controllare la visualizzazione 
delle linee della griglia (cgGridLines = true), permettendo l'attivazione delle 
opzioni secondarie (contrazione ed espansione delle dimensioni con indicatori + e 
- ; cgOutliner = true), e l'attivazione della rotazione tramite "drag and drop" 
(cgPivotable = true)). 

• L'evento OnDecisionDraivCell di TDecisionGrid consente di modificare l'aspetto di 
ciascuna cella mentre viene disegnata. L'evento passa String, Font e Color della 
cella attiva come parametri di riferimento. E possibile modificare questi parametri 
per realizzare effetti come, ad esempio, colori speciali per indicare valori negativi. 
Oltre a DrawState, che e passato da TCustomGrid, l'evento passa 
TDecisionDrawState, che puo essere usato per determinare quale tipo di cella viene 
disegnando. E possibile ottenere ulteriori informazioni sulla cella utilizzando le 
funzioni Cells, CellValue Array, o CellDr aw State. 

• L'evento OnDecisionExamineCell di TDecisionGrid consente di agganciare l'evento 
"clic destro" sulle celle dei dati, ed e stato creato per permettere al programma di 
visualizzare informazioni (come ad esempio i record di dettaglio) su quella 
determinata cella di dati. Quando l'utente fa clic col tasto destro su una cella di 
dati, all'evento vengono fornite tutte le informazioni usate per comporre i valori 
dei dati, compresi il valore di riepilogo attualmente attivo e un ValueArray di tutti i 
valori della dimensione usati per creare il valore di riepilogo. 

Creazione e uso dei grafici decisionali 



I componenti grafico decisionale, TDecisionGraph, presentano dati incrociati in 
formato grafico. Ciascun grafico decisionale mostra il valore di un singolo riepilogo, 
come Sum, Count, o Avg, tracciato per una o piu dimensioni. Per maggiori 
informazioni sui crosstab, consultare la pagina 20-3. Per illustrazioni di grafici 
decisionali in fase di progetto, vedere la Figura 20.1 a pagina 20-2 e la Figura 20.4 a 
pagina 20-15. 
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Creazione di grafici decisionali 



Per creare una scheda con uno o piu grafici decisionali: 

1 Seguire le istruzioni da 1 a 3 elencate nella sezione "Regole generali per l'uso dei 
componenti di supporto decisionale" a pagina 20-3. 

2 Aggiungere uno o piu componenti grafici decisionali (TDecisionGraph) e collegarli 
con l'Object Inspector alia sorgente decisionale, TDecisionSource, impostandone la 
proprieta DecisionSource al componente della sorgente decisionale opportuno. 

3 Procedere con le istruzioni da 5 a 7 elencate nella sezione "Regole generali per 
l'uso dei componenti di supporto decisionale". 

4 Per finire, fare clic col tasto destro sul grafico e selezionare Edit Chart per 
modificare l'aspetto della serie del grafico. Per ciascuna dimensione del grafico e 
possibile impostare delle proprieta campione, e impostare poi singolarmente una 
serie di proprieta per sostituire quelle predefinite. Per maggiori informazioni, 
consultare la sezione "Personalizzazione dei grafici decisionali" a pagina 20-16. 

Per una descrizione di cio che appare nel grafico decisionale e del modo in cui usarlo, 
consultare la prossima sezione "Uso dei grafici decisionali". 

Per aggiungere una griglia decisionale o una tabella crosstab alia scheda, seguire le 
istruzioni della sezione "Creazione e uso delle griglie decisionali" a pagina 20-11. 

Uso dei grafici decisionali 



II componente grafico decisionale, TDecisionGraph, visualizza i campi provenienti 
dalla sorgente decisionale (TDecisionSource) come un grafico dinamico che si 
modifica quando le dimensioni dei dati vengono aperte, chiuse, spostate con "drag- 
and-drop" o riordinate con il pivot decisionale (TDecisionPivot). 

I dati trasformati in grafico provengono da un dataset specificamente formattato 
come TDecisionQuery. Per una panoramica su come i componenti di supporto 
decisionale gestiscono e ordinano questi dati, consultare la pagina 20-1. 

Per impostazione predefinita, la prima dimensione della riga appare come l'asse 
delle x e la prima dimensione della colonna appare come l'asse delle y. 

E possibile usare i grafici decisionali in alternativa o in aggiunta alle griglie 
decisionali, che presentano dati incrociati in forma tabellare. Le griglie decisionali e i 
grafici decisionali che sono collegati alia stessa sorgente decisionale presentano le 
stesse dimensioni di dati. Per mostrare i diversi dati di riepilogo per le stesse 
dimensioni, e possibile collegare piu di un grafico decisionale alia stessa sorgente 
decisionale. Per mostrare dimensioni diverse, collegare i grafici decisionali a sorgenti 
decisionali diverse. 

Nella Figura 20.4, ad esempio, il primo pivot decisionale e il primo grafico sono 
collegati alia prima sorgente decisionale, mentre il secondo pivot decisionale e il 
secondo grafico sono collegati alia seconda. In questo modo, ciascun grafico mostra 
dimensioni diverse. 
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Figura 20.4 Grafici decisionali collegati a sorgenti decisionali diverse 
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Per maggiori informazioni su cio che appare in un grafico decisionale, consultare la 
prossima sezione "Visualizzazione del grafico decisionale". 

Per creare un grafico decisionale, consultare la sezione precedente "Creazione di 
grafici decisionali". 

Per una trattazione delle proprieta del grafico decisionale e delle modalita per 
modificare l'aspetto e il comportamento dei grafici decisionali, consultare 
"Personalizzazione dei grafici decisionali" a pagina 20-16. 



Visualizzazione del grafico decisionale 



Per impostazione predefinita, il grafico decisionale traccia i valori di riepilogo delle 
categorie nel primo campo attivo della riga (lungo l'asse delle y) rispetto ai valori nel 
primo campo attivo della colonna (lungo l'asse delle x). Ogni categorie riportata nel 
grafico appare come una serie separata. 

Se viene selezionata una sola dimensione — ad esempio, facendo clic solamente su un 
pulsante di TDecisionPivot — viene riportata in grafico una sola serie. 

Se si e utilizzato un pivot decisionale, e possibile premerne i pulsanti per determinare 
quali campi del cubo decisionale (dimensioni) devono essere riportati in grafico. Per 
scambiare gli assi del grafico, trascinare i pulsanti di dimensione del pivot 
decisionale da un lato all'altro dello spazio separatore. Se si ha un grafico mono- 
dimensionale con tutti i pulsanti disposti su un solo lato dello spazio separatore, e 
possibile usare l'icona Row o l'icona Column per aggiungere pulsanti sull'altro lato 
del separatore e trasformare il grafico in multidimensionale. 
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Per attivare una sola riga e una sola colonna alia volta, e possibile impostare la 
proprieta ControlType di TDecisionSource a xtRadio. A quel punto, ci puo essere un 
solo campo attivo alia volta per ciascun asse del cubo decisionale, mentre la 
funzionalita del pivot decisionale corrispondera al comportamento del grafico. 
xtRadioEx funziona in modo analogo a xtRadio, ma non prevede la condizione in cui 
tutte le dimensioni della riga o della colonna siano chiuse. 

Quando la griglia e il grafico decisionali sono connessi alio stessa TDecisionSource, 
sara probabilmente opportuno reimpostare ControlType a xtCheck in modo che 
corrisponda al comportamento piu flessibile di TDecisionGrid. 

Personalizzazione dei grafici decisionali 



II componente grafico decisionale, TDecisionGraph, visualizza i campi provenienti 
dalla sorgente decisionale (TDecisionSource) come un grafico dinamico che si 
modifica quando le dimensioni dei dati vengono aperte, chiuse, spostate con "drag- 
and-drop", o quando vengono riordinate usando il pivot decisionale (TDecisionPivot). 
E possibile modificare tipo, colori, tipi di contrassegni per le linee del grafico e molte 
altre proprieta dei grafici decisionali. 

Per personalizzare un grafico: 

1 Fare clic col tasto destro sul grafico e scegliere Edit Chart. Apparira la finestra di 
dialogo Chart Editing. 

2 Usare la pagina Chart della finestra di dialogo Chart Editing per visualizzare un 
elenco di serie visibili, selezionare la definizione della serie da usare quando, per 
una stessa serie, ve ne sono due o piu disponibili, modificare i tipi di grafico per 
un modello o per una serie, e impostare le proprieta complessive del grafico. 

L'elenco Series sulla pagina Chart mostra tutte le dimensioni del cubo decisionale 
(precedute da Template:) e le categorie attualmente visibili. Ciascuna categoria o 
serie e un oggetto separato. E possibile: 

• Aggiungere o cancellare serie derivare da serie esistenti del grafico decisionale. 
Le serie derivate sono in grado di fornire annotazioni su serie esistenti o 
rappresentare valori calcolati da altre serie. 

• Modificare il tipo di grafico predefinito e il titolo dei modelli e delle serie. 

Per una descrizione degli altri separatori della pagina Chart cercare l'argomento 
"Chart page (Chart Editing dialog box)" nella Guida in linea. 

3 Usare la pagina Series per impostare i modelli delle dimensioni, e personalizzare 
poi le proprieta per ogni singola serie del grafico. 

Per impostazione predefinita, tutte le serie vengono tracciate come grafici a barre a 
cui vengono assegnati fino a 16 colori. E possibile modificare il tipo di modello e le 
proprieta per creare una nuova impostazione predefinita. Poi, mentre si agisce sulla 
sorgente decisionale facendola passare a stati differenti, il modello viene usato per 
creare dinamicamente le serie per ciascun nuovo stato. Per maggiori dettagli sui 
modelli, consultare "Impostazioni predefinite dei modelli di grafico decisionale" a 
pagina 20-17. 
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Per personalizzare le singole serie, seguire le istruzioni in "Personalizzazione delle 
serie del grafico decisionale" a pagina 20-18. 

Per una descrizione dei separatori della pagina Series, cercare l'argomento "Series 
page (Chart Editing dialog box)" nella Guida in linea. 

Impostazioni predefinite dei modelli di grafico decisionale 

I grafici decisionali visualizzano i valori provenienti da due dimensioni del cubo 
decisionale: una dimensione e visualizzata come un asse del grafico, l'altra e usata 
per creare un insieme di serie. II modello di quella dimensione fornisce le proprieta 
predefinite per quelle serie (per esempio, se le serie sono barre, linee, aree e cosi via). 
Via via che gli utenti passano da uno stato all'altro, tutte le serie richieste per la 
dimensione vengono create utilizzando il tipo di serie e le altre impostazioni 
predefinite specificate nel modello. 

Per i casi in cui gli utenti passano ad uno stato con una sola dimensione attiva, viene 
fornito un modello separate Un stato monodimensionale viene spesso rappresentato 
con un grafico a torta, e quindi, per questo caso, viene fornito un modello a parte. 

E possibile 

• Modificare il tipo di grafico predefinito. 

• Modificare altre proprieta del modello grafico. 

• Visualizzare e impostare le proprieta complessive del grafico. 

Modifica del tipo di grafico decisionale predefinito 

Per modificare il tipo di grafico predefinito: 

1 Selezionare un modello nell'elenco Series della pagina Chart della finestra di 
dialogo Chart Editing. 

2 Fare clic sul pulsante Change. 

3 Selezionare un nuovo tipo e chiudere la finestra di dialogo Gallery. 

Modifica di altre proprieta del modello di grafico decisionale 

Per modificare il colore o le altre proprieta di un modello: 

1 Selezionare la pagina Series nella parte superiore della finestra di dialogo Chart 
Editing. 

2 Scegliere un modello nell'elenco a discesa nella parte superiore della pagina. 

3 Scegliere l'opportuno separatore proprieta e selezionare le impostazioni. 

Visualizzazione delle proprieta complessive del grafico decisionale 

Per vedere e impostare proprieta del grafico decisionale diverse dal tipo e dalle serie: 

1 Selezionare la pagina Chart nella parte superiore della finestra di dialogo Chart 
Editing. 

2 Scegliere l'opportuno separatore proprieta e selezionare le impostazioni. 
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Personalizzazione delle serie del grafico decisionale 

I modelli fomiscono molte impostazioni predefinite per ciascuna dimensione del 
cubo decisionale, quali, ad esempio, i tipi di grafico e il modo in cui le serie vengono 
visualizzate. Le altre impostazioni predefinite, quale, ad esempio, il colore della serie, 
sono definite da TDecisionGraph. Volendo, e possibile sostituire le impostazioni 
predefinite di ciascuna serie. 

I modelli sono stati ideati per i casi in cui il programma debba creare serie per le 
categorie, man mano che queste si rendono necessarie, ed eliminarle quando non lo 
sono piu. Volendo, e possibile impostare serie personalizzate per determinati valori 
della categoria. Per fare cio occorre agire sul grafico in modo che la vista attuale 
presenti una serie per la categoria che si vuole personalizzare. Quando la serie e 
visualizzata sul grafico, si puo usare il Chart editor per: 

• Modificare il tipo di grafico. 

• Modificare le altre proprieta della serie. 

• Salvare le serie del grafico che sono state personalizzate. 

Per definire i modelli della serie e impostare le impostazioni predefinite complessive 
del grafico, consultare la sezione "Impostazioni predefinite dei modelli di grafico 
decisionale" a pagina 20-17. 

Modifica del tipo di grafico delle serie 

Per impostazione predefinita, ciascuna serie ha lo stesso tipo di grafico, definito dal 
modello per la sua dimensione. Per modificare tutte le serie e fare in modo che 
abbiano tutte lo stesso tipo di grafico, e possibile modificare il tipo di modello. Per 
istruzioni consultare il paragrafo "Modifica del tipo di grafico decisionale 
predefinito" a pagina 20-17. 

Per modificare il tipo di grafico per una singola serie: 

1 Selezionare una serie nell'elenco Series della pagina Chart di Chart editor. 

2 Fare clic sul pulsante Change. 

3 Selezionare un nuovo tipo e chiudere la finestra di dialogo Gallery. 

4 Spuntare la casella di controllo Save Series. 

Modifica di altre proprieta delle serie del grafico decisionale 

Per modificare il colore o le altre proprieta di una serie di un grafico decisionale: 

1 Selezionare la pagina Series nella parte superiore della finestra di dialogo Chart 
Editing. 

2 Scegliere una serie nell'elenco a discesa nella parte superiore della pagina. 

3 Scegliere l'opportuno separatore proprieta e selezionare le impostazioni. 

4 Spuntare la casella di controllo Save Series. 
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Salvataggio delle impostazioni delle serie del grafico decisionale 

Per impostazione predefinita, solamente le impostazioni dei modelli vengono salvate 
in fase di progetto. Le modifiche apportate a una determinata serie vengono salvate 
solo se la casella Save e attiva per quella serie nella finestra di dialogo Chart Editing. 

II salvataggio delle serie puo essere dispendioso in termini di memoria, quindi, se 
non occorre salvarle si puo disattivare la casella Save. 

Componenti di supporto decisionale in esecuzione 



Durante l'esecuzione, gli utenti possono compiere molte operazioni facendo clic col 
tasto sinistra, destro e trascinando i componenti di supporto decisionale visibili. 
Queste operazioni, descritte nelle sezioni precedenti di questo capitolo, sono 
riassunte di seguito. 

Pivot decisionali in esecuzione 



Gli utenti possono: 

• Fare clic con il tasto sinistra sul pulsante di riepilogo all'estremita sinistra del pivot 
decisionale per visualizzare l'elenco di riepiloghi disponibili. Possono usare 
questo elenco per modificare i dati di riepilogo visualizzati in griglie e grafici 
decisionali. 

• Fare clic col tasto destro su un pulsante di dimensione e scegliere di: 

• Spostarlo dall'area della riga all'area della colonna o viceversa. 

• Selezionare Drill In per visualizzare i dati nel dettaglio. 

• Fare clic con il tasto sinistro su uno dei pulsanti di dimensione dopo il comando 
Drill In e scegliere: 

• Open Dimension per ritornare al livello superiore di quella dimensione. 

• All Values per passare dalla visualizzazione dei soli riepiloghi alia 
visualizzazione dei riepiloghi e di tutti gli altri valori nelle griglie decisionali. 

• Da un elenco di categorie disponibili per quella dimensione, selezionare una 
categoria da sondare per avere i valori nel dettaglio. 

• Fare clic con il tasto sinistro su un pulsante di dimensione per aprire o chiudere 
quella dimensione. 

• Trascinare e rilasciare i pulsanti di dimensione dall'area della riga all'area della 
colonna e viceversa; possono essere rilasciati accanto ai pulsanti esistenti in 
quell'area o sull'icona della riga o della colonna. 

Griglie decisionali in esecuzione 



Gli utenti possono: 
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• Fare clic col tasto destro all'intemo della griglia decisionale e scegliere di: 

• Attivare o disattivare i totali parziali per singoli gruppi di dati, per tutti i valori 
di una dimensione o per la griglia intera. 

• Visualizzare il Decision Cube editor, descritto a pagina 20-7. 

• Aprire e chiudere le dimensioni e i riepiloghi. 

• Fare click su + e su - all'intemo delle intestazioni di riga e di colonna per aprire e 
chiudere le dimensioni. 

• Trascinare e rilasciare le dimensioni dalle righe alle colonne e viceversa. 

Grafici decisionali in esecuzione 



Gli utenti possono trascinare le dimensioni da lato aU'altro o in su e in giu neU'area 
della griglia del grafico per fare scorrere sullo schermo categorie e valori. 

Componenti di supporto decisionale e controllo della memoria 



II caricamento di una dimensione o di un riepilogo nel cubo decisionale richiede 
parecchia memoria. L'aggiunta di un nuovo riepilogo incrementa il consumo di 
memoria in modo lineare: ovvero, un cubo decisionale che dispone di due riepiloghi 
utilizza il doppio della memoria che lo stesso userebbe con un riepilogo solo; un cubo 
decisionale con tre riepiloghi usa il triplo della memoria che lo stesso userebbe con 
un solo riepilogo e cosi via. L'aumento del consumo della memoria per le dimensioni 
e ancora piu rapido. L'aggiunta di una dimensione con 10 valori aumenta il consumo 
di memoria di dieci volte. L'aggiunta di una dimensione con 100 valori aumenta il 
consumo di memoria di 100 volte. Quindi, l'aggiunta di dimensioni a un cubo 
decisionale pud avere un effetto drammatico sull'uso della memoria, e pud causare 
rapidamente problemi di prestazioni. Questo effetto e particolarmente evidente 
quando si aggiungono dimensioni che hanno molti valori. 

I componenti di supporto decisionale dispongono di un certo numero di 
impostazioni che aiutano l'utente a controllare come e quando la memoria viene 
usata. Per maggiori informazioni sulle proprieta e sulle tecniche descritte in questa 
sezione, consultare TDecisionCube nella Guida in linea. 

Impostazione dei valori massimi per dimensioni, riepiloghi e celle 



Le proprieta MaxDimensions e MaxSummaries del cubo decisionale possono essere 
usate con la proprieta CubeDim->ActiveFlag per controllare il numero di dimensioni e 
di riepiloghi che e possibile caricare in una sola volta.E possibile impostare i valori 
massimi sulla pagina Cube Capacity del Decision Cube editor per introdurre un 
controllo complessivo sul numero di dimensioni o di riepiloghi da portare 
contemporaneamente in memoria. 

Limitando il numero delle dimensioni o dei riepiloghi, si ottiene un calcolo 
approssimativo della quantita di memoria usata dal cubo decisionale. Comunque, 
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non e possibile distinguere tra dimensioni con molti valori e dimensioni con pochi 
valori. Per avere un controllo piu preciso dello spazio assoluto di memoria richiesto 
dal cubo decisionale, e possibile limitare anche il numero delle celle nel cubo. 
Impostare il numero massimo di celle sulla pagina Cube Capacity del Decision Cube 
editor. 

Impostazione dello stato della dimensione 



La proprieta ActiveFlag controlla quali dimensioni vengono caricate. E possibile 
impostare questa proprieta sul separatore Dimension Settings del DecisionCube 
editor utilizzando il controllo Activity Type. Quando questo controllo e impostato ad 
Active, non ci sono limiti nel caricamento della dimensione che quindi occupera 
sempre piu spazio. Si noti che il numero di dimensioni in questa condizione deve 
sempre essere inferiore a quello di MaxDimensions, e il numero dei riepiloghi 
impostati ad Active deve essere inferiore a quello di MaxSummaries. Si dovrebbe 
impostare una dimensione o un riepilogo ad Active solo se e indispensabile che siano 
sempre disponibili. Un'impostazione Active diminuisce la capacita del cubo di gestire 
la memoria disponibile. 

Quando ActiveFlag e impostato a AsNeeded, una dimensione o un riepilogo vengono 
caricati solamente se e possibile farlo senza superare i limiti di MaxDimensions, 
MaxSummaries o di MaxCells. II cubo decisionale gestira le dimensioni e i riepiloghi 
contrassegnati da AsNeeded eseguendo swap di memoria per caricarli e scaricarli, in 
modo da rimanere nei limiti imposti da MaxCells, MaxDimensions e MaxSummaries. In 
questo modo, una dimensione o un riepilogo non possono essere caricati in memoria 
se in quel momento non sono utilizzati. L'impostazione delle dimensioni che non 
vengono usate di frequente, come AsNeeded, comporta un miglioramento delle 
prestazioni in fase di caricamento e di gestione, anche se l'accesso alle dimensioni 
non caricate risultera leggermente piu lento. 

Utilizzo delle dimensioni paginate 



Quando Binning e impostato a Set nella pagina Dimension Settings del Decision 
Cube editor e Start Value non e NULL, la dimensione si dice essere "paginata" o 
"permanentemente espansa". E possibile accedere ai dati solo per un singolo valore 
alia volta di quella dimensione, sebbene da programma sia possibile accedere a una 
serie di valori in modo sequenziale. Tale dimensione non puo essere usata come 
pivot o aperta. 

E estremamente dispendioso, dal punto di vista della memoria, includere dati 
dimensionali per le dimensioni che hanno un numero elevato di valori. Paginando 
tali dimensioni, e possibile visualizzare informazioni di riepilogo per un valore alia 
volta. Solitamente, quando vengono visualizzate in questo modo, le informazioni 
sono piu facili da leggere e il consumo di memoria e molto piu semplice da gestire. 
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21 



Connessione 



ai database 



La maggior parte dei component! dataset puo collegarsi direttamente a un server di 
database. Appena connesso, il dataset comunica con il server automaticamente. 
Quando si apre il dataset, esso si popola con i dati dal server e quando si registrano i 
record, essi vengono restituiti al server e applicati. Un singolo componente 
connection SQL puo essere condiviso da piu dataset oppure ciascun dataset puo 
utilizzare la propria connessione. 

Ogni tipo del dataset si collega al server di database utilizzando il proprio tipo di 
componente connection, progettato per funzionare con un singolo meccanismo di 
accesso ai dati. La seguente tabella elenca questi meccanismi di accesso ai dati e i 
componenti connection associati: 



Tabella 21.1 Componenti di connessione del database 



Meccanismo di accesso ai dati 


Componente connection 


Borland Database Engine (BDE) 


TDatabase 


ActiveX Data Objects (ADO) 


TADOConnection 


dbExpress 


TSQLConnection 


InterBase Express 


TIBDatabase 



Per una trattazione dei pro e contro di ciascuno di questi meccanismi consultare "Uso 
dei databases" a pagina 18-1. 

II componente connection fornisce tutte le informazioni necessarie per stabilire una 
connessione al database. Queste informazioni sono diverse per ogni tipo di 
componente connection: 

• Per informazioni sulla descrizione di una connessione basata su BDE, vedere 
"Identificazione del database" a pagina 24-14. 

• Per informazioni sulla descrizione di una connessione basata su ADO, vedere 
"Connessione a un datastore mediante TADOConnection" a pagina 25-3. 
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• Per informazioni sulla descrizione di una connessione dbExpress, vedere 
"Impostazione di TSQLConnection" a pagina 26-3. 

• Per informazioni sulla descrizione di una connessione InterBase Express, vedere la 
Guida in linea per TIBDatabase. 

Benche ogni tipo di dataset utilizzi un componente connection diverso, tali 
componenti discendono tutti da T Custom-Connection. Tutti quanti assolvono 
moltissimi compiti identici e rendono disponibili molte proprieta, metodi ed eventi 
identici. II presente capitolo tratta la maggior parte di queste attivita comuni. 

Uso di connessioni implicite 



Indipendentemente dal meccanismo di accesso ai dati utilizzato, e sempre possibile 
creare il componente connection in modo esplicito e utilizzarlo per gestire la 
connessione a un server di database e la comunicazione con esso. Per dataset BDE e 
basati su ADO, c'e la possibility di descrivere la connessione al database tramite 
proprieta del dataset e di permettere al dataset di generare una connessione 
implicita. Per i dataset BDE, si specifica una connessione implicita utilizzando la 
proprieta DatabaseName. Per i dataset basati su ADO, si utilizza la proprieta 
ConnectionString. 

Quando si utilizza una connessione implicita, non e necessario creare esplicitamente 
un componente connection. Cio puo semplificare lo sviluppo dell'applicazione e la 
connessione predefinita che si specifica puo coprire un'ampia gamma di situazioni. 
Per applicazioni client/ server complesse e cruciali, con molti utenti e diversi requisiti 
per connessioni al database, comunque, si consiglia di creare i propri componenti 
connection in modo da adattare ciascuna connessione di database alle necessita 
dell'applicazione. I componenti connection espliciti offrono un maggiore controllo. 
Ad esempio, e necessario accedere al componente connection per eseguire le seguenti 
operazioni: 

• Personalizzare il supporto per il login al server di database, (le connessioni 
implicite visualizzano una finestra di dialogo di login predefinita per richiedere 
all'utente un nome utente e una password.) 

• Controllare le transazioni e specificarne i livelli di isolamento delle transazioni. 

• Eseguire comandi SQL sul server senza utilizzare un dataset. 

• Compiere operazioni su tutti i dataset aperti che sono connessi alio stesso 
database. 

Inoltre, se si hanno piu dataset che utilizzano tutti lo stesso server, potrebbe essere 
piu semplice utilizzare un componente connection, in modo che si debba specificare 
una sola volta il server da utilizzare. In questo modo, se in un secondo momento si 
modifichera il server, non sara necessario aggiornare tutti i componenti dataset ma 
solo il componente connection. 
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Controllo delle connessioni 



Prima di potere stabilire una connessione a un server di database, l'applicazione deve 
fornire determinate informazioni chiave che descrivono il server desiderate Ogni 
tipo di componente connection rende disponibile un diverso set di proprieta per 
permettere l'identificazione del server. Di solito, comunque, offrono tutti un modo 
per assegnare il nome del server desiderato e per fornire un set di parametri di 
connessione che controllano il modo in cui viene stabilita la connessione. I parametri 
di connessione variano da server a server. Possono includere informazioni come 
nome utente e password, dimensione massima dei campi BLOB, ruoli SQL, e cosi via. 

Una volta identificati il server richiesto e tutti i parametri di connessione, e possibile 
utilizzare il componente connection per aprire o chiudere esplicitamente una 
connessione. All'apertura e alia chiusura di una connessione, il componente 
connection genera eventi che e possibile utilizzare per personalizzare la risposta 
dell'applicazione alle modifiche nella connessione al database. 

Connessione a un server di database 



Esistono due modi per connettersi a un server database usando un componente 
connection: 

• Chiamando il metodo Open. 

• Impostando la proprieta Connected a true. 

La chiamata del metodo Open imposta Connected a true. 

Quando un componente connection non e connesso a un server e un'applicazione 
tenta di aprire i dataset a lui associati, il dataset chiama automaticamente il metodo 
Open del componente connection. 

Quando si imposta Connected a true, il componente connection genera per prima cosa 
un evento BeforeConnect, in cui e possibile eseguire qualsiasi inizializzazione. Ad 
esempio, e possibile utilizzare questo evento per modificare i prametri di 
connessione. 

Dopo l'evento BeforeConnect, il componente connection puo visualizzare una finestra 
di dialogo predefinita per il login, a seconda di come si sceglie di controllare il login 
al server. Quindi passa al driver il nome utente e la password, aprendo una 
connessione. 

Una volta aperta la connessione, il componente connection genera un evento 
AfterConnect in cui e possibile eseguire qualsiasi operazione che richieda una 
connessione aperta. 

Alcuni componenti connection generano anche altri eventi nel momento in cui 
stabiliscono una connessione. 

Una volta che la connessione e stata stabilita, tale connessione viene mantenuta attiva 
finche e'e almeno un dataset attivo che la utilizza. Quando non ci sono piu dataset 
attivi, il componente connection rilascia la connessione. Alcuni componenti 
connection rendono disponibile una proprieta KeepConnection che permette alia 
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connessione di rimanere aperta anche se tutti i dataset che la utilizzano sono chiusi. 
Se Keep 'Connection e impostato a true, la connessione viene mantenuta aperta. Per 
connessioni a server di database remoti o per applicazioni che aprono e chiudono 
dataset con una certa frequenza, l'impostazione di KeepConnection a true riduce il 
traffico di rete e velocizza l'applicazione. Se KeepConnection e impostato a false, la 
connessione viene interrotta appena non vi sono piu dataset attivi che utilizzano il 
database. Se un dataset che utilizza il database viene aperto in un secondo momento, 
la connessione deve essere ristabilita e inizializzata. 

Disconnessione da un server di database 



Esistono due modi per sconnettersi da un server usando un componente connection: 

• Impostando la proprieta Connected a false. 

• Chiamata al metodo Close. 
La chiamata a Close imposta Connected a false. 

Quando la proprieta Connected e impostata a false, il componente connection genera 
un evento BeforeDisconnect in cui e possibile eseguire qualsiasi operazione di pulizia 
prima che la connessione venga chiusa. Ad esempio, e possibile utilizzare questo 
evento per memorizzare nella cache le informazioni su tutti i dataset aperti prima che 
essi vengano chiusi. 

Dopo l'evento BeforeConnect, il componente connection chiude tutti i dataset aperti e 
si scollega dal server. 

Infine, il componente connection genera un evento AfterDisconnect in cui e possibile 
rispondere alia modifica nello stato della connessione, come ad esempio l'attivazione 
di un pulsante Connect dell'interfaccia utente. 

La chiamata al metodo Close o l'impostazione della proprieta Connected a false causa 
lo scollegamento da un server di database anche se la proprieta KeepConnection del 
componente connection e impostata a true. 

Controllo del login al server 



La maggior parte dei server database remoti includono funzioni di sicurezza per 
proibire l'accesso non autorizzato. Generalmente, il server richiede un nome utente e 
una password di login prima di consentire l'accesso al database. 

In fase di progettazione, se un server richiede un login, C++Builder visualizza una 
finestra di dialogo Login standard che, quando si tenta di connettersi al database per 
la prima volta, richiede il nome dell'utente e la password. 

In fase di esecuzione, ci sono tre modi con cui gestire la richiesta di login del server: 

• Consentire la gestione del login alia finestra di dialogo di login e di elaborazione. 
Questo e il metodo predefinito. Impostare la proprieta LoginPrompt del 
componente connection a true (impostazione predefinita) e aggiungere 
DBLogDlg.hpp alia clausola che dichiara il componente connection. 
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L'applicazione visualizzera la finestra di dialogo di login standard appena il 
server richiede un nome utente e una password. 

• Fornire le informazioni di login prima del tentativo di login. Ogni tipo di 
componente connection utilizza un meccanismo diverso per la specifica del nome 
utente e della password: 

• Per i dataset BDE, dbExpress e InterBaseExpress, si puo accedere ai parametri di 
connessione nome utente e password tramite la proprieta Params. (Per i dataset 
BDE, i valori dei parametri possono essere associati anche a un alias BDE, 
mentre per i dataset dbExpress possono essere associati anche a un nome di 
connessione). 

• Per i dataset ADO, il nome utente e la password possono essere inclusi nella 
proprieta ConnectionString (o forniti come parametri al metodo Open). 

Se si specificano nome utente e password prima che il server li richieda, accertarsi 
di impostare il LoginPrompt a false, in modo che non venga visualizzata la finestra 
di dialogo login predefinita. Ad esempio, il codice seguente imposta il nome e la 
password dell'utente per un componente SQ1 connection nel gestore di evento 
BeforeConnect, decifrando una password crittografata memorizzata associata al 
nome di connessione corrente: 

void __fastcall TForml: :SQLConnectionBeforeConnect (TObject *Sender) 
{ 

if (SQLConnectionl->LogiiiPrompt == false) 
{ 

SQLConnectionl->Params->Values [''UserJJame" ] = " SYSDBA" ; 
SQLConnectionl->Params->Values ["Password" ] = 

Decrypt (SQLConnectionl->Params->Values ["Password" ] ) ; 

} 

} 

Si noti che l'impostazione del nome utente e della password in fase di 
progettazione o l'utilizzo di stringhe direttamente nel codice fa si che i valori 
vengano incorporati nel file eseguibile dell'applicazione. In questo modo, i valori 
sono ancora abbastanza facilmente reperibili, compromettendo in tal modo la 
sicurezza del server. 

• Preparare la propria gestione custom per l'evento di login. II componente 
connection genera un evento quando ha bisogno del nome utente e della 
password. 

• Per TDatabase, TSQLConnection e TIBDatabase questo e un evento OnLogin. II 
gestore di evento ha due parametri, il componente connection e una copia 
locale dei parametri nome utente e password in una lista di stringhe. 
(TSQLConnection include anche il parametro database). Perche questo evento si 
verifichi, e necessario impostare la proprieta LoginPrompt a true. Un valore di 
LoginPrompt impostato a false e l'assegnazione di un gestore all'evento OnLogin 
crea una situazione in cui e impossibile connettersi al database perche la 
finestra di dialogo predefinita non viene visualizzata e il gestore di evento 
OnLogin non sara mai eseguito. 

• Per TADOConnection, l'evento e un evento OnWillConnect. II gestore di evento 
ha cinque parametri, il componente connection e quattro parametri che 
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restituiscono valori per influire sulla connessione (di cui due per nome utente e 
password). Questo evento si verifica sempre, indipendentemente dal valore di 
LoginPrompt. 

Scrivere un gestore di evento per l'evento in cui si impostano i parametri di login. 
Di seguito e riportato un esempio in cui i valori per i parametri USER NAME e 
PASSWORD sono forniti mediante una variabile globale (UserName) e un metodo 
che, a fronte di un nome utente (PasswordSearch), restituisce una password) 

void __fastcall TForml: :DatabaselLogin(TDatabase *Database, TStrings *LoginParams) 

{ 

LoginParams->Values ["USER NAME"] = UserName; 
LoginParams->Values ["PASSWORD"] = PasswordSearch (UserName) ; 

} 

Come gia visto con gli altri metodi utilizzati per fornire i parametri di login, 
quando si scrive un gestore di evento OnLogin o OnWillConnect e bene evitare di 
scrivere esplicitamente la password nel codice dell'applicazione. La password 
dovrebbe apparire solo come valore crittograf ato, come un elemento in un 
database sicuro utilizzato dall'applicazione per cercare il valore, oppure dovrebbe 
essere ottenuta dinamicamente dall'utente. 

Gestione delle transazioni 



Una transazione e un gruppo di azioni che devono essere tutte portate a termine con 
successo su una o piu tabelle di un database prima che siano compiute (rese 
permanenti). Se una delle azioni nel gruppo non riesce, allora tutte le azioni vengono 
fatte scorrere a ritroso (annullate). Utilizzando le transazioni, nel caso si verifichi un 
problema durante il compimento di una delle azione che compongono la 
transazione, ci si assicura che il database non venga lasciato in uno stato 
incongruente. 

Ad esempio, in un'applicazione bancaria, il trasferimento di fondi da un conto 
all'altro e un'operazione che sarebbe bene proteggere con una transazione. Se, dopo 
aver decrementato il saldo di un conto, si verifica un errore incrementando il saldo 
dell'altro, sara possibile annullare la transazione in modo che il database rifletta 
ancora il saldo totale corretto. 

E sempre possibile gestire le transazioni inviando comandi SQL direttamente al 
database. Quasi tutti i database sono dotati di un proprio modello per la gestione 
delle transazioni, benche alcuni non forniscano alcun supporto per le transazione. 
Per i server che le supportano, potrebbe essere necessario scrivere in prima persona il 
codice per la gestione delle transazioni, sfruttando le capacita di gestione di 
transazioni avanzate esistenti su un particolare server di database, come la cache di 
schema. 

Se non e necessario utilizzare queste capacita evolute di gestione delle transazioni, i 
componenti connection mettono a disposizione un insieme di metodi e proprieta che 
e possibile utilizzare per gestire le transazioni senza inviare esplicitamente alcun 
comando SQL. L'utilizzo di queste proprieta e di questi metodi offre il vantaggio che 
non e necessario personalizzare l'applicazione per ogni tipo di server di database 
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utilizzato, sempre che il server supporti le transazioni. (Anche BDE fornisce un 
supporto limitato per le transazione con tabelle locali che non dispongono di 
supporto per transazioni del server). (Se non si utilizza BDE il tentativo di avviare le 
transazioni su un database che non le supporta provoca il sollevamento di 
un'eccezione da parte dei componenti connection.) 

Quando un componente dataset provider applica gli aggiornamenti, genera 
implicitamente transazioni per qualsiasi aggiornamento. E bene prestare attenzione 
al fatto che qualsiasi transazione iniziata esplicitamente non vada in conflitto con 
quelle generati dal provider. 

Awio di una transazione 



Quando si avvia una transazione, tutte le successive istruzioni di lettura o di scrittura 
nel database si verificano nel contesto di quella transazione, finche la transazione non 
viene terminata esplicitamente o, nel caso di transazioni sovrapposte, finche non 
viene avviata un'altra transazione. Ogni istruzione e considerata parte di un gruppo. 
Tutte le modifiche dovranno essere registrate con successo nel database, altrimenti 
sara necessario annullare ogni modifica fatta nel gruppo. 

Mentre la transazione e in corso, la vista dei dati nelle tabelle di database e 
determinata dal livello di isolamento della transazione. Per ulteriori informazioni sui 
livelli di isolamento delle transazioni, consultare "Specifica del livello di isolamento 
delle transazioni" a pagina 21-10. 

Per TADOConnection awiare una transazione chiamando il metodo BeginTrans: 

Level = ADOConnectionl->BeginTrans ( ) ; 

BeginTrans restituisce il livello di annidamento della transazione appena iniziata. 
Una transazione annidata e una transazione inclusa aU'interno di un'altra 
transazione genitore. Dopo che il server ha avviato la transazione, la connessione 
ADO riceve un evento OnBeginTransComplete. 

Per TDatabase, utilizzare il metodo StartTransactionmethod invece. TDataBase non 
supporta transazioni annidate o sovrapposte: Se si chiama il metodo StartTransaction 
di un componente TDatabase mentre e in corso un'altra transazione, il componente 
solleva un'eccezione. Per evitare di chiamare StartTransaction, e possibile controllare 
la proprieta InTransaction property: 

if ( !Databasel->lnTransaction) 
Databasel->StartTransaction() ; 

Anche TSQLConnection utilizza il metodo StartTransaction ma la versione utilizza 
offre un controllo maggiore. Nello specifico, StartTransaction accetta un descrittore di 
transazione che permette di gestire piu transazioni simultanee e di specificare il 
livello di isolamento delle transazioni, transazione per transazione. (Per ulteriori 
informazioni sui livelli delle transazioni, vedere "Specifica del livello di isolamento 
delle transazioni" a pagina 21-10.) Per gestire piu transazioni simultanee, impostare 
il campo TransactionID del descrittore di transazione a un valore univoco. 
TransactionID puo essere un qualsiasi valore scelto dall'utente, a patto che sia 
univoco (non sia cioe in conflitto con una qualsiasi altra transazione attualmente in 
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esecuzione). A seconda del server, le transazioni avviate da TSQLConnection possono 
essere annidate (come quando si utilizza ADO) o sovrapposte. 

TTransactionDesc TD; 
TD.TransactionID = 1; 
TD.ISOlatlonLevel = xi 1READC0MMITTED ; 
SQLConnec tionl->St art Transact ion (TD) ; 

Per impostazione predefinita, nel caso di transazioni sovrapposte, la prima 
transazione diventa inattiva non appena parte la seconda transazione, benche sia 
possibile rimandare la conferma o l'annullamento della prima transazione ad una 
fase successiva. Se si utilizza TSQLConnection con un database InterBase, e possibile 
identificare ogni dataset nell'applicazione con una particolare transazione attiva, 
impostandone la proprieta TransactionLevel. Cio significa che, dopo avere awiato una 
seconda transazione, e possibile continuare a gestire contemporaneamente entrambe 
le transazioni, semplicemente associando un dataset alia transazione che si desidera. 

A differenza di TADOConnection, TSQLConnection e TDatabase non ricevono alcun 
evento quando parte la transazione. 

InterBase Express offre un controllo ancora maggiore rispetto a quello di 
TSQLConnection perche utilizza un componente di transazione separate) invece di un 
singolo componente connection che avvia anche le transazioni. E possibile utilizzare, 
tuttavia, TIBDatabase per avviare una transazione predefinita: 

if ( ! lBDatabasel->DefaultTransaction->lnTransaction) 
lBDatabasel->DefaultTransaction->StartTransaction( ) ; 

E possibile ottenere transazioni sovrapposte utilizzando due componenti di 
transazione separati. Ogni componente di transazione ha un set di parametri che 
permettono di configurare la transazione. Questi parametri permettono di specificare 
il livello di isolamento della transazione, oltre ad altre proprieta. 

Chiusura di una transazione 



Idealmente, una transazione dovrebbe durare solo il tempo necessario. Piu a lungo 
una transazione e attiva, maggiore e il numero di utenti che accedono 
simultaneamente al database, e piu e grande il numero di transazioni simultanee che 
vengono avviate e terminano durante l'esistenza della transazione, maggiore e la 
probability che la transazione sia in conflitto con un'altra quando si tentera di 
confermare una qualsiasi modifica. 

Chiusura di una transazione andata a buon fine 

Non appena tutte le azioni che compongono la transazione sono andate a buon fine, e 
possibile rendere permanenti le modifiche al database confermando la transazione. 
Per TDatabase, si convalida una transazione utilizzando il metodo Commit: 

MyOracleConnection->Coimit ( ) ; 

Anche per TSQLConnection si utilizza il metodo Commit ma e necessario specificare 
quale transazione si sta convalidando fornendo lo stesso descrittore della transazione 
passato al metodo StartTransaction: 
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MyOracleConnection->Coiranit (TD) ; 
Per TIBDatabase, si convalida un oggetto transazione utilizzando il metodo Commit: 

IBDatabasel->Def aultTransaction->Commit ( ) ; 

Per TADOConnection, si convalida una transazione utilizzando il metodo 
CommitTrans: 

ADOConnectionl->CornmitTrans ( ) ; 

E possibile convalidare una transazione annidata, solo af finche sia possibile 
annullare le le modifiche in un secono momento nel caso venga annullata la 
transazione genitore. 

Dopo che la transazione e stata convalidata con successo, un componente connection 
ADO riceve un evento OnCommitTransComplete. Altri componenti connection non 
ricevono un tale evento. 

Una chiamata per convalidare la transazione corrente di solito viene tentata in un 
blocco di istruzioni try...catch. In questo modo, se la transazione non viene inoltrata 
con esito positivo, e possibile utilizzare il blocco catch per gestire l'errore e ritentare 
l'operazione oppure per eseguire il roll-back della transazione. 

Chiusura di una transazione non andata a buon fine 

Nel caso si verifichi un errore durante l'esecuzione delle modifiche che fanno parte 
della transazione o durante la conferma della transazione, si rendera necessario 
eliminare tutte le modifiche apportate dalla transazione. L'abbandono delle 
modifiche e detto annullamento, o roll-back, della transazione. 

Per TDatabase, si annulla una transazione chiamando il metodo Rollback: 

MyOracleConnection->Rollback( ) ; 

Per TSQLConnection, e possibile usaare anche il metodo Rollback, ma e necessario 
specificare quale transazione si sta annullando fornendo il descrittore della transazione 
passato al metodo StartTransaction: 

MyOracleConnection->Rollback(TD) ; 

Per TIBDatabase, e possibile annullare un oggetto transaction chiamandone il metodo 
Rollback: 

lBDatabasel->DefaultTransaction->Rollback( ) ; 
Per TADOConnection, si annulla una transazione chiamando il metodo RollbackTrans: 

ADOConnectionl->RollbackTrans ( ) ; 

Dopo che la transazione e stata annullata con successo, un componente ADO 
connection riceve un evento OnRollbackTransComplete. Altri componenti connection 
non ricevono un tale evento. 

Una chiamata per annullare la transazione corrente di solito si verifica 

• Nella porzione di codice che gestisce l'eccezione, nel caso sia impossibile 
ripristinare un errore di database. 
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• Nel codice dell'evento di un pulsante o di un menu, ad esempio quando l'utente fa 
clic su un pulsante Cancel. 

Specifica del livedo di isolamento delle transazioni 



II livello di isolamento della transazione determina come una transazione interagisce 
con altre transazioni simultanee quando operano con le stesse tabelle. In particolare, 
influenza quanto una transazione "vede" delle altre modifiche apportate dalle 
transazioni a una tabella. 

Ogni tipo di server supporta un diverso set di possibili livelli di isolamento della 
transazione. Esistono tre possibili livelli di isolamento di una transazione: 

• DirtyRead: Quando il livello di isolamento e DirtyRead, la transazione vede tutte le 
modifiche fatte da altre transazioni, anche se tali modifiche non sono stati 
confermate. Le modifiche non confermate non sono permanenti e potrebbero 
essere annullate in qualsiasi momento. Questo valore fornisce il livello di 
isolamento minimo e non e disponibile per molti server di database (come Oracle, 
Sybase, MS-SQL e InterBase). 

• ReadCommitted: Quando il livello di isolamento e ReadCommitted, risultano visibili 
solo le modifiche confermate fatte da altre transazioni. Benche questa 
impostazione impedisca alia transazione di vedere le modifiche non confermate e 
che potrebbero essere annullate, nel caso un'altra transazione venga conf ermata 
durante la fase di lettura della transazione in corso, e tuttavia possibile che si abbia 
una vista incongruente dello stato del database. Questo livello e disponibile per 
tutte le transazioni tranne che per le transazioni locali gestite da BDE. 

• RepeatableRead: Quando il livello di isolamento e RepeatableRead, alia transazione 
viene garantita la visione di uno stato congruente dei dati del database. La 
transazione vede una singola istantanea dei dati. Non e in grado di vedere 
nessuna successiva modifica ai dati da parte di altre transazioni simultanee, anche 
nel caso in cui le mdifiche vengano confermate. Questo livello di isolamento 
garantisce che una volta che la transazione ha letto un record, la vista di quel 
record non cambiera. A questo livello la transazione risulta veramente isolata dalle 
modifiche fatte da altre transazioni. Questo livello e non disponibile su alcuni 
server, come Sybase e MS-SQL e non e disponibile per transazioni locali gestite da 
BDE. 

Inoltre, TSQLConnection permette di specificare livelli di isolamento custom, specifici 
per un certo database. I livelli di isolamento custom sono definiti dal driver 
dbExpress. Consultare la documentazione del driver per i dettagli. 

Per una descrizione dettagliata dell'implementazione di ogni livello di isolamento, 
consultare la documentazione del server. 

TDatabase e TADOConnection permettono di specificare il livello di isolamento della 
transazione impostando la proprieta Translsolation. Quando si imposta Translsolation 
a un valore che non e supportato dal server di database, si ottiene il successivo livello 
di isolamento piu elevato (se disponibile). Se non c'e alcun livello piu elevato 
disponibile, appena si prova ad awiare una transazione il componente connection 
solleva un'eccezione. 
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Utilizzando TSQLConnection, il livello di isolamento della transazione e controllato 
dal campo IsolationLevel del descrittore della transazione. 

Utilizzando InterBase Express, il livello di isolamento della ttransazione e controllato 
da un parametro della transazione. 

Invio di comandi al server 



Tutti i componenti database connection, tranne 77BDa£atase,permettono di eseguire 
istruzioni SQL sul server associato chiamando il metodo Execute. Benche Execute 
possa restituire un cursor nel caso l'istruzione sia un'istruzione SELECT, questo 
utilizzo non e consigliato. II metodo preferenziale per l'esecuzione di istruzioni che 
restituiscono dati e quello di utilizzare un dataset. 

II metodo Execute e molto comodo per l'esecuzione di semplici istruzioni SQL che 
non restituiscono record. Tali istruzioni includono istruzioni Data Definition 
Language (DDL), che operano sui metadati di un database o li creano, come CREATE 
INDEX, ALTER TABLE e DROP DOMAIN. Anche alcune istruzioni DML (Data 
Manipulation Language) di SQL non restituiscono un set risultato. Le istruzioni DML 
che compiono un'azione sui dati ma non restituiscono un set risultato sono: INSERT, 
DELETE e UPDATE. 

La sintassi del metodo Execute varia in funzione del tipo di connessione: 

• Per TDatabase, Execute accetta quattro parametri: una stringa Ansi che specifica la 
singola istruzione SQL che si desidera eseguire, un oggetto TParams che fornisce 
tutti i valori dei parametri per quell'istruzione, un valore boolean che indica se 
l'istruzione deve essere messa in cache o meno perche la si vorra eseguire di 
nuovo, e un puntatore a un cursor BDE che puo essere restituito. (Si consiglia di 
passare il valore NULL). 

• Per TADOConnection, esistono due versioni di Execute. La prima versione richiede 
una WideString che specifica l'istruzione SQL e un secondo parametro che 
specifica un set di opzioni che controllano se l'istruzione viene eseguita in modo 
asincrono o se restituisce dei record. Questa prima sintassi restituisce 
un'interfaccia per i record restituiti. La seconda sintassi richiede una WideString 
che specifica l'istruzione SQL, un secondo parametro che restituisce il numero di 
record interessati dall'esecuzione dell'istruzione, e un terzo parametro che 
specifica varie opzioni, come, ad esempio, se l'istruzione viene eseguita in modo 
asincrono. Notare che nessuna delle due sintassi consente il passaggio di 
parametri. 

• Per TSQLConnection, Execute accetta tre parametri, una stringa ANSI che specifica 
la singola istruzione SQL che si desidera eseguire, un oggetto TParams che fornisce 
tutti i valori dei parametri per quell'istruzione e un puntatore che puo ricevere un 
oggetto TCustomSQLDataSet creato per restituire ai record il valore NULL. 

Execute puo solo eseguire un'istruzione SQL alia volta. Non e possibile per eseguire 
piu istruzioni SQL con una singola chiamata a Execute, come di solito si fa con i 
programmi di utilita di scrittura di codice SQL. Per eseguire piu di un'istruzione, 
chiamare Execute piu volte. 
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E relativamente facile eseguire un'istruzione che non include nessun parametro. Ad 
esempio, il seguente codice esegue un'istruzione CREATE TABLE (DDL) senza alcun 
parametro su un componente TSQLConnection: 

void __fastcall TDataForm: :CreateTableButtonClick(TObject *Sender) 

{ 

SQLConnectionl->Connected = true; 
AnsiString SQLstmt = " CREATE TABLE NewCusts " + 
"| » + 

11 CustNo INTEGER, " + 
" Company CHAR (40) , " + 
" State CHAR (2), 11 + 

11 PRIMARY KEY (CustNo) " + 

")"; 

SQLConnectionl->Execute (SQLstmt, NULL, NULL); 

} 

Per utilizzare parametri, e necessario creare un oggetto TParams. Per ogni valore di 
parametro utilizzare il metodo TParams, per aggiungere un oggetto TParam utilizzare 
il metodo CreateParam. Quindi utilizzare le proprieta di TParam per descrivere il 
parametro e impostarne il valore. 

Questo procedimento e illustrato nell'esempio seguente che utilizza TDatabase per 
eseguire un'istruzione INSERT. L'istruzione INSERT ha un singolo parametro con 
nome -.StateParam. Viene creato un oggetto TParams (di nome stmtParams) per fornire 
il valore "CA" a quel parametro. 

void __fastcall TForml: : INSERT_WithParamsButtonClick (TObject *Sender) 

{ 

AnsiString SQLstmt; 

TParams *stmtParams = new TParams; 

try 

{ 

Databasel->Connected = true; 

stmtParams->CreateParam(ftString, "StateParam", ptlnput); 
stmtParams->ParamByName ( "StateParam" ) ->AsString = "CA"; 
SQLstmt = "INSERT INTO ' Custom. db' "; 
SQLstmt += "(CustNo, Company, State) "; 

SQLstmt += "VALUES (7777, ' Robin Dabank Consulting 1 , : StateParam) " ; 
Databasel->Execute (SQLstmt, stmtParams, false, NULL); 

} 

__finally 

{ 

delete stmtParams; 

} 

} 

Se l'istruzione SQL include un parametro ma non e stato preparato un oggetto 
TParam per fornirgli un valore, l'istruzione SQL puo generare un errore al momento 
dell'esecuzione (questo dipende dal particolare back-end di database utilizzato). Se 
viene fornito un oggetto TParam ma non c'e alcun parametro corrispondente 
nell'istruzione SQL, quando l'applicazione tenta di utilizzare TParam viene sollevata 
un'eccezione. 
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Operazioni con i dataset associati 



Tutti i componenti per la connessione ai database gestiscono una lista di tutti i 
dataset attivi che li utilizzano per collegarsi a un database. Un componenente 
connection utilizza questa lista, ad esempio, per chiudere tutti i dataset nel momento 
in cui chiude la connessione al database. 

E possibile utilizzare questa lista anche per eseguire azioni su tutti i dataset che 
utilizzano uno specifico componente connection per collegarsi a un particolare 
database. 

Chiusura dei dataset senza scollegarsi dal server 



II componente connection chiude automaticamente tutti i dataset quando si chiude la 
sua connessione. A volte potrebbe essere necessario chiudere tutti i dataset senza 
scollegarsi dal server di database. 

Per chiudere tutti i dataset aperti senza scollegarsi da un server, si puo usare il 
metodo CloseDataSets. 

Per TADOConnection e per TIBDatabase, la chiamata a CloseDataSets lascia sempre 
aperta la connessione. Per TDatabase e per TSQLConnection, e inoltre necessario 
impostare la proprieta KeepConnection a true. 

Scansione di tutti i dataset associati 



Per eseguire qualsiasi altra azione (diversa dalla chiusura) su tutti i dataset che 
utilizzano un componente connection, utilizzare le proprieta DataSets e DataSetCount. 
DataSets e un array con indice di tutti i dataset che sono collegati con il componente 
connection. Per tutti i componenti connection, tranne TADOConnection, questa lista 
include solo i dataset attivi. TADOConnection elenca anche i dataset non attivi. 
DataSetCount e il numero dei dataset in questo array. 

Quando si utilizza un dataset client specializzato per memorizzare gli aggiornamenti 
in cache (diversamente dal dataset client generico, TClientDataSet), la proprieta 
DataSets elenca il dataset interno posseduto dal dataset client, non il dataset client 
stesso. 

E possibile utilizzare DataSets con DataSetCount per passare in sequenza attraverso 
tutti i dataset correntemente attivi nel codice. Ad esempio, il seguente codice passa in 
sequenza tutti i dataset attivi e disabilita tutti i controlli che utilizzano i dati da essi 
forniti: 

for (int i = 0; i < MyDBConnection->DataSetCount ; i++) 
MyDBConnection->DataSets [i] ->DisableControls ( ) ; 

Oltre ai dataset, TADOConnection supporta anche oggetti command. E possibile 
iterare tra questi oggetti esattamente come si iterano tra i dataset, utilizzando le 
proprieta Commands e CommandCount. 
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Ottenimento di metadati 



Tutti i componenti database connection possono acquisire dal server di database liste 
di metadati, benche essi si differenzino in base al tipo di metadati che acquisiscono. I 
metodi per l'acquisizione di metadati riempiono una lista di stringhe con i nomi delle 
diverse entita disponibili sul server. E possibile utilizzare quindi queste 
informazioni, ad esempio, per permettere agli utenti di selezionare dinamicamente 
una tabella in fase di esecuzione. 

E possibile utilizzare un componente TADOConnection per acquisire metadati sulle 
tabelle e sulle procedure registrate disponibili nel datastore ADO. E possibile 
utilizzare quindi queste informazioni, ad esempio, per permettere agli utenti di 
selezionare dinamicamente una tabella o una procedura registrata in fase di 
esecuzione. 

Elenco delle tabelle disponibili 



II metodo GetTableNames copia una lista di nomi di tabelle in un oggetto string list gia 
esistente. In questo modo, ad esempio, si puo riempire una casella di riepilogo con i 
nomi delle tabelle disponibili, utilizzabile dall'utente per scegliere una tabella da 
aprire. La riga seguente riempie una casella di riepilogo con i nomi di tutte le tabelle 
del database: 

MyDBConnection->GetTableNames (ListBoxl->Items , false ) ; 

GetTableNames ha due parametri: la lista di stringhe da riempire con i nomi delle 
tabelle, e un parametro boolean che indica se la lista deve includere le tabelle di 
sistema o le tabelle comuni. Si noti che non tutti i server utilizzano tabelle di sistema 
per memorizzare i metadati; pertanto la richiesta di tabelle di sistema potrebbe 
generare una lista vuota. 

Per la maggior parte dei componenti database connection, se il secondo parametro e 
impostato a false, il metodo GetTableNames restituisce una lista di tutte le tabelle non 
di sistema disponibili. Per TSQLConnection, tuttavia, si ha un maggior controllo sui 
tipi di tabella aggiunti alia lista quando non si prelevano solo i nomi delle tabelle di 
sistema. Se si utilizza TSQLConnection, i tipi dei nomi aggiunti alia lista sono 
controllati dalla proprieta TableScope. TableScope indica se la lista dovra contenere uno 
o tutti i seguenti tipi: tabelle comuni, tabelle di sistema, sinonimi e viste. 

Elenco dei campi in una tabella 



II metodo GetFieldNames riempie una stringa esistente con i nomi di tutti i campi 
(colonne) presenti in una tabella specificata. GetFieldNames ha due parametri, il nome 
della tabella di cui si desidera elencare i campi e una lista di stringhe esistente da 
riempire con i nomi dei campi: 

MyDBConnection->GetTableNames ( "Employee" , ListBoxl->Items) ; 
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Elenco delle procedure registrate disponibili 



Per ottenere un elenco di tutte le procedure registrate presenti nel database, utilizzare 
il metodo GetProcedureNames. Questo metodo ha un singolo parametro: una lista di 
stringhe gia esistente da riempire: 

MyDBConnection->GetProcedureNames (ListBoxl->Items ) ; 

GetProcedureNames e disponibile solo per TADOConnection e TSQLConnection. 

Elenco degli indici disponibili 



Per ottenere un elenco di tutti gli indici di una certa tabella, utilizzare il metodo 
GetlndexNames. Questo metodo ha due parametri: la tabella di cui si desidera ottenere 
gli indici e una lista di stringhe gia esistente da riempire: 

MyDBConnectionl->GetIndexNames ("Employee", ListBoxl->Items) ; 

GetlndexNames e disponibile solo per TSQLConnection, benche la maggior parte dei 
dataset di tipo tabella abbia un metodo equivalente. 



Elenco dei parametri delle procedure registrate 



Per ottenere un elenco di tutti i parametri di una certa procedura registrata, utilizzare 
il metodo GetProcedureParams. GetProcedureParams riempie un oggetto TList con dei 
puntatori ai structure di descrizione dei parametri, in cui ogni structure descrive un 
parametro di una procedura registrata specificata, inclusi nome, indice, tipo di 
parametro, tipo di campo, e cosi via. 

GetProcedureParams ha due parametri: il nome della procedura registrata e un oggetto 
TList gia esistente da riempire: 

MyDBConnectionl->GetIndexNames ( "GetlnterestRate" , Listl) ; 

Per convertire queste descrizioni dei parametri aggiunte alia lista in un oggetto 
TParams piu familiare chiamare la procedura globale LoadParamListltemsprocedure. 
Poiche GetProcedureParams alloca dinamicamente i singoli record, l'applicazione deve 
liberarli una volta che ha recuperato le informazioni. La routine globale 
FreeProcParams puo farlo automaticamente. 

GetProcedureParams e disponibile solo per TSQLConnection. 
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I dataset 



L'unita fondamentale per accedere ai dati e la famiglia di oggetti dataset. Le 
applicazioni usano i dataset per tutti gli accessi ai database. Un oggetto dataset 
rappresenta un insieme di record di un certo database organizzati in una tabella 
logica. Questi record possono essere i record da una singola tabella di database o 
possono rappresentare i risultati dell'esecuzione di una query o di una procedura 
registrata. 

Tutti gli oggetti dataset che vengono usati nelle applicazioni database discendono da 
TDataSet, ed ereditano da questa classe campi dati, proprieta, eventi e metodi. 
Questo capitolo descrive le funzionalita di TDataSet che vengono ereditate dagli 
oggetti dataset che si useranno nelle applicazioni database. Per poter utilizzare 
qualsiasi oggetto dataset e necessario comprendere queste funzionalita condivise. 

TDataSet e un dataset 'virtualizzato', nel senso che molte delle sue proprieta e dei 
suoi metodi sono virtual o pure virtual. Un metodo virtual e una dichiarazione di 
funzione o di procedura, la cui implementazione puo essere (e solitamente lo e) 
ridefinita negli oggetti discendenti. Un metodo pure virtual e una dichiarazione di 
funzione o di procedura senza una reale implementazione. La dichiarazione e un 
prototipo che descrive il metodo (e i relativi parametri e tipi restituiti, se ce ne sono) 
da implementare in tutti gli oggetti dataset discendenti, ognuno dei quali potrebbe 
pero implementarlo in modo differente. 

Poiche TDataSet contiene metodi pure virtual, non puo essere usato direttamente in 
un'applicazione senza generare un errore in esecuzione. Per owiare a questo 
inconveniente, e possibile o creare istanze dei discendenti interni di TDataSet e usarle 
nell'applicazione, oppure derivare un proprio oggetto dataset da TDataSet o dai suoi 
discendenti, e scrivere le implementazioni per tutti i suoi metodi pure virtual. 

TDataSet definisce molte caratteristiche comuni a tutti gli oggetti dataset. TDataSet 
definisce, ad esempio, la struttura di base di tutti i dataset: un array di componenti 
TField che corrispondono alle colonne effettive in una o piu tabelle database, campi di 
consultazione o campi calcolati forniti dall'applicazione. Per maggiori informazioni 
sui componenti, consultare Capitolo 23, "Operazioni con i componenti campo". 
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Questo capitolo descrive come utilizzare le comuni funzionalita di database 
introdotte da TDataSet. Tenere presente, comunque, che benche TDataSet introduca i 
metodi per queste funzionalita, non tutti i discendenti da TDataSet li implementano. 
In particolare, i dataset unidirezionali implementano solo un sottoinsieme limitato. 

Utilizzo dei discendenti di TDataSet 



TDataSet ha numerosi discendenti diretti, ognuno di cui corrisponde a un 
meccanismo di accesso dati diverse Non si opera direttamente con nessuno di questi 
discendenti. Invece, ogni discendente introduce le proprieta e i metodi per l'utilizzo 
di un particolare meccanismo di accesso ai dati. Queste proprieta e questi metodi 
sono quindi esposti da classi discendenti che sono adattate a vari tipi di server di 
dati. I discendenti immediati di TDataSet includono 

• TBDEDataSet, che utilizza Borland Database Engine (BDE) per comunicare con il 
server di database. I discendenti di TBDEDataSet che si utilizzano sono TTable, 
TQuery, TStoredProc e TNestedTable. Le funzioni tipiche dei dataset basati su BDE 
sono descritte nel Capitolo 24, "Uso di Borland Database Engine". 

• TCustomADODataSet, che utilizza ActiveX Data Objects (ADO) per comunicare 
con un datastore OLEDB. I discendenti di TCustomADODataSet che si utilizzano 
sono TADODataSet, TADOTable, TADOQuery e TADOStoredProc. Le funzioni 
tipiche dei dataset basati su ADO sono descritte nel Capitolo 25, "Operazioni con 
componenti ADO". 

• TCustomSQLDataSet, che utilizza dbExpress per comunicare con un server di 
database. I discendenti di TCustomSQLDataSet che si utilizzano sono TSQLDataSet, 
TSQLTable, TSQLQuery e TSQLStoredProc. Le funzioni tipiche dei dataset 
dbExpress sono descritte nel Capitolo 26, "Uso di dataset unidirezionali". 

• TIBCustomDataSet, che comunica direttamente con un server di database 
InterBase. I discendenti di TIBCustomDataSet che si utilizzano sono TIBDataSet, 
TIBTable, TIBQuery e TIBStoredProc. 

• TCustomClientDataSet, che rappresenta i dati da un altro componente dataset o i 
dati da un file dedicato su disco. I discendenti di TCustomClientDataSet che si 
utilizzano sono TClientDataSet , che puo collegarsi a un dataset (sorgente) esterno e 
i dataset client che sono specializzati per un particolare meccanismo di accesso ai 
dati (TBDEClientDataSet, TSQLClientDataSet e TIBCHentDataSet), i quali utilizzano 
un dataset sorgente interno. Le funzioni tipiche dei dataset client sono descritte nel 
Capitolo 27, "Utilizzo dei dataset client". 

Alcuni pro e contro dei diversi meccanismi di accesso ai dati impiegati da questi 
discendenti di TDataSet sono descritti in "Uso dei databases" a pagina 18-1. 

Oltre ai dataset nativi, e possibile creare propri discendenti custom di TDataSet - ad 
esempio per fornire dati da un processo diverso rispetto a un server di database, ad 
esempio da un foglio elettronico. La scrittura di dataset custom offre la flessibilita di 
gestire i dati utilizzando un metodo qualsiasi a propria scelta, consentendo al 
contempo di utilizzare i controlli dati della VCL per costruire l'interfaccia utente. Per 
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ulteriori informazioni sulla creazione di componenti personalizzati, consultare il 
Capitolo 45, "Introduzione alia creazione di componenti". 

Benche ogni discendente di TDataSet abbia proprie proprieta e metodi unici, alcune 
proprieta e alcuni metodi introdotti dalle classi discendenti sono gli stessi di quelli 
introdotti da altre classi discendenti che utilizzano un altro meccanismo di accesso di 
dati. Ad esempio, tra i componenti "tabella" (TTable, TADOTable, TSQLTable e 
TIBTable) vi sono similitudini. Per informazioni sulle caratteristiche comuni 
introdotte dai discendenti di TDataSet, vedere "Tipi di dataset" a pagina 22-24. 



Determinazione degli stati del dataset 



Lo stato — o modalita — di un dataset determina le operazioni possibili con i relativi 
dati. Per esempio, quando un dataset e chiuso, il suo stato e dslnactive, owero 
nessuna operazione e consentita sui suoi dati. In fase di esecuzione, e possibile 
esaminare la proprieta a sola lettura State di un dataset per determinare lo stato 
corrente di quest'ultimo. La seguente tabella riepiloga i valori possibili per la 
proprieta State e il relativo significato: 



Tabella 22.1 Valori della proprieta State di un dataset 
Valore Stato 

dslnactive Inactive 
dsBrowse Browse 



dsEdit Edit 

dslnsert Insert 

dsSetKey SetKey 

dsCalcFields CalcFields 

dsCurValue CurValue 

dsNewValue NewValue 

dsOldValue OldValue 



dsFilter 



Filter 



Significato 

II dataSet e chiuso. I suoi dati non sono disponibili. 

II DataSet e aperto. I suoi dati possono essere visualizzati, ma 
non modificati. Questo e lo stato predefinito di un dataset 
aperto. 

II DataSet e aperto. La riga corrente puo essere modificata. (non 
supportato nei dataset unidirezionali) 

II DataSet e aperto. E possibile inserire una nuova riga. (Non 
supportato nei dataset unidirezionali) 

II DataSet e aperto. Consente l'impostazione di intervalli e valori 
chiave usati per gli intervalli e le operazioni GotoKey. 
(Supportato dat tutti i dataset) 

II DataSet e aperto. Indica che e in corso un evento OnCalcFields. 
Impedisce di apportare modifiche a campi che non siano 
calcolati. 

II DataSet e aperto. Indica che la proprieta CurValue dei campi 
viene prelevata da un gestore di evento che risponde agli errori 
durante l'applicazione degli aggiornamenti in cache. 

II DataSet e aperto. Indica che la proprieta NewValue dei campi 
viene prelevata da un gestore di evento che risponde agli errori 
durante l'applicazione degli aggiornamenti in cache. 

II DataSet e aperto. Indica che la proprieta OldValue dei campi 
viene prelevata da un gestore di evento che risponde agli errori 
durante l'applicazione degli aggiornamenti in cache. 

II DataSet e aperto. Indica che e in corso un'operazione di filtro. 
E possibile visualizzare una serie limitata di dati, ma non e 
possibile modificare alcun dato. (Non supportato nei dataset 
unidirezionali) 
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e chiusura di dataset 



Tabella 22.1 Valori della proprieta State di un dataset 
Valore Stato Significato 

dsBlockRead Block Read II DataSet e aperto. I controlli data-aware non vengono 

aggiornati e gli eventi non vengono innescati quando si modifica 
il record corrente. 

dsInternalCalc Internal Calc II DataSet e aperto. E in corso un evento OnCalcFields per i valori 

calcolati che sono memorizzati con il record. (Solo con dataset 
client) 

dsOpening Opening II dataSet e in fase di apertura ma l'operazione non e terminata. 

Questo stato si verifica quando il dataset viene aperto per il 
prelievo asincrono. 



Di solito, un'applicazione controlla lo stato di dataset per determinare quando 
eseguire determinate operazioni. Ad esempio, si potrebbe controllare lo stato dsEdit o 
dslnsert per verificare se e necessario registrare gli aggiornamenti. 

A ogni cambiamento dello stato di un dataset, l'evento OnStateChange viene chiamato 
per qualsiasi componente datasource associato al dataset. Per ulteriori informazioni 
sui componenti datasource e su OnStateChange, vedere "Risposta alle modifiche 
mediate dal datasource" a pagina 19-4. 



Apertura e chiusura di dataset 

Per leggere o modificare i dati in un dataset, un'applicazione deve innanzi tutto 
aprirlo. Per aprire un dataset e possibile procedere in due modi, 

• Impostare la proprieta Active del dataset a true, in fase di impostazione nell'Object 
Inspector, oppure in fase di esecuzione nel codice: 

CustTable->Active = true; 

• Chiamare il metodo Open del dataset in fase di esecuzione, 

CustQuery->Open() ; 

Quando si apre il dataset, il dataset riceve dapprima un evento BeforeOpen quindi 
apre un cursor, si riempie di dati e, infine, riceve un evento AfterOpen. 

II dataset appena aperto e in modalita browse, il che significa che l'applicazione puo 
leggere i dati e spostarsi tra di loro. 

E possibile chiudere un dataset in due modi, 

• Impostare la proprieta Active del dataset a false, in fase di impostazione 
nell'Object Inspector, oppure in fase di esecuzione nel codice, 

CustQuery->Active = false; 

• Chiamare il metodo Close per il dataset in fase di esecuzione, 

CustTable->Close() ; 

Esattamente come riceve eventi BeforeOpen e AfterOpen quando lo si apre, il dataset 
riceve un evento BeforeClose e AfterClose quando lo si chiude. E possibile scrivere 
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gestori di evento che rispondono al metodo Close di un dataset. E possibile usare 
questi eventi, ad esempio, per chiedere a un utente di registrare o annullare le 
modifiche in sospeso prima di chiudere il dataset. II seguente codice illustra tale 
gestore: 

void __fastcall TForral : :VerifyBeforeClose (TDataSet *DataSet) 
{ 

if (DataSet->State == dsEdit I I DataSet->State == dslnsert) 

{ 

TMsgDlgButtons btns; 
btns « mbYes « mbNo; 

if (MessageDlg ( "Post changes before closing?", mtConfirmation, btns, 0) == mrYes) 

DataSet->Post() ; 
else 

DataSet->Cancel() ; 

} 

} 

Quando si desidera modificare determinate proprieta, ad esempio TableName di un 
componente TTable, puo essere necessario chiudere il dataset. Quando si riapre il 
dataset, i nuovi valori delle proprieta diventano effettivi. 

Spostamenti nei dataset 



Ogni dataset attivo ha un cursore, o puntatore, che indica la riga corrente del dataset. 
La riga corrente di un dataset e quella i cui valori di campo appaiono nei controlli 
associati ai dati e riferiti a un singolo campo di una scheda, quali TDBEdit, TDBLabel e 
TDBMemo. Se il dataset supporta l'editing, il record corrente contiene valori che 
possono essere trattati dai metodi per l'editing, l'inserimento e la cancellazione. 

La riga corrente puo essere cambiata spostando il cursore in modo tale che punti a 
un'altra riga. La seguente tabella elenca i metodi utilizzabili nei codice di 
un'applicazione per passare ad altri record: 

Tabella 22.2 Metodi di navigazione dei dataset 



Metodo 


Sposta II cursore a 


First 


La prima riga in un dataset. 


Last 


L'ultima riga in un dataset. (Non disponibile per dataset unidirezionali) 


Next 


La riga successiva in un dataset. 


Prior 


La riga precedente in un dataset. (Non disponibile per dataset unidirezionali) 


MoveBy 


Un numero di righe specificate in avanti o a ritroso in un dataset. 



II componente visuale associato ai dati TDBNavigator incapsula questi metodi come 
pulsanti selezionabili dagli utenti per spostarsi tra i record in fase di esecuzione. Per 
ulteriori informazioni sul componente Navigator, vedere "Spostamento e gestione 
dei record" a pagina 19-31. 

Ogni volta che si modifica il record corrente utilizzando uno di questi metodi (o da 
altri metodi di navigazione che agiscono in base a un criterio di ricerca), il dataset 
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riceve due eventi: BeforeScroll (prima di lasciare il record corrente) e AfterScroll (dopo 
essere arrivato sul nuovo record). E possibile utilizzare questi eventi per aggiornare 
l'interfaccia utente (ad esempio, per aggiornare una barra di stato riporta 
informazioni sul record corrente). 

TDataSet definisce due proprieta booleane che forniscono informazioni utili sulla 
posizione del cursore tra i record di un dataset. 

Tabella 22.3 Proprieta di navigazione dei dataset 
Proprieta Descrizione 

Bof (Beginning-of-file) true: il cursore si trova in corrispondenza della prima riga del dataset. 

false: il cursore non e stato trovato in corrispondenza della prima riga 
del dataset 

Eo/(End-of-file) true: il cursore si trova in corrispondenza dell'ultima riga del dataset. 

false: il cursore non e stato trovato in corrispondenza della prima riga 
del dataset 



Utilizzo dei metodi First e Last 



II metodo First sposta il cursore alia prima riga di un dataset e imposta la proprieta 
Bof a true. Se il cursore e gia alia prima riga del dataset, First non esegue alcuna 
operazione. 

Ad esempio, il seguente codice determina lo spostamento del cursore al primo record 
di CustTable: 

CustTable->First() ; 

II metodo Last sposta il cursore all'ultima riga di un dataset e imposta la proprieta Eof 
a true. Se il cursore e gia all'ultima riga del dataset, Last non esegue alcuna 
operazione. 

II seguente codice determina lo spostamento del cursore all'ultimo record di 
CustTable: 

CustTable->Last() ; 

II metodo Last solleva un'eccezione con i dataset unidirezionali. 



Anche se possono esservi motivi pratici di programmazione per spostare il cursore 
alia prima o all'ultima riga di un dataset senza l'intervento dell'utente, lo 
sviluppatore puo anche permettere agli utenti di spostarsi tra i record, awalendosi 
del componente TDBNavigator. II componente Navigator contiene una serie di 
pulsanti che, quando sono attivi e visibili, consentono aU'utente di posizionarsi alia 
prima o all'ultima riga di un dataset attivo. Gli eventi OnClick per questi pulsanti 
chiamano i metodi First e Last del dataset. Per ulteriori informazioni sull'utilizzo 
efficace del componente Navigator, vedere "Spostamento e gestione dei record" a 
pagina 19-31. 
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II metodo Next sposta il cursore alia riga successiva nel dataset e imposta la proprieta 
Bof a false se il dataset non e vuoto. Se il cursore si trova gia all'ultima riga del 
dataset quando si chiama Next, non accade nulla. 

Ad esempio, il seguente codice sposta il cursore al record successivo in CustTable: 

CustTable->Next() ; 

II metodo Prior fa arretrare il cursore alia riga precedente nel dataset e imposta Eo/a 
false se il dataset non e vuoto. Se il cursore si trova gia alia prima riga del dataset 
quando si chiama Prior, non accade nulla. 

Ad esempio, il seguente codice sposta il cursore al record precedente in CustTable: 

CustTable->Prior() ; 
II metodo Prior solleva un'eccezione con i dataset unidirezionali. 

Utilizzo del metodo MoveBy 

MoveBy consente di specificare quante righe avanti o indietro il cursore deve essere 
spostato in un dataset. Lo spostamento e relativo al record corrente al momento della 
chiamata di MoveBy. MoveBy imposta inoltre in modo appropriato le proprieta Bofe 
Eo/per il dataset. 

Questa funzione legge un parametro rappresentato da un numero intero che indica il 
numero di record dello spostamento. I numeri interi positivi designano uno 
spostamento in avanti, mentre i numeri interi negativi designano uno spostamento 
all'indietro. 

MoveBy solleva un'eccezione con i dataset unidirezionali se si utilizza un argomento 
con segno negative 

MoveBy restituisce il numero di righe dello spostamento. Se si cerca di oltrepassare 
l'inizio o la fine del dataset, il numero di righe restituito da MoveBy differisce dal 
numero di righe richieste per lo spostamento. Questo perche MoveBy si ferma 
quando raggiunge il primo o l'ultimo record del dataset. 

II seguente codice determina lo spostamento a ritroso di due righe in CustTable: 

CustTable->MoveBy (-2) ; 

Se l'applicazione usa MoveBy in un ambiente database multiutente, occorre tenere 
presente che i dataset sono dinamici. Se piu utenti possono accedere 
simultaneamente al database e modificarne i dati, un record che un attimo prima era 
in posizione arretrata di cinque record, nell'arco di pochi istanti, potrebbe essere 
arretrato di quattro o sei o addirittura di un numero indeterminato di record. 
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Utilizzo delle proprieta Eof e Bof 



Due proprieta a sola lettura utilizzabili in fase di esecuzione, Eof (End-of-file) e Bof 
(Beginning-of-file), risultano utili quando si desidera elaborare in modo iterativo tutti 
i record di un dataset. 

Eof 

Quando Eofe true, indica che il cursore e inequivocabilmente posizionato sull'ultima 
riga di un dataset. Eofe impostato a true quando un'applicazione 

• Apre un dataset vuoto. 

• Chiama il metodo Last di un dataset. 

• Chiama il metodo Next di un dataset e il metodo non riesce a compiere alcuna 
operazione (perche il cursore si trova all'ultima riga del dataset). 

• Chiama SetRange su un intervallo o dataset vuoto. 

In tutti gli altri casi, Eofe false; si deve presupporre che Eof sia false, a meno che si 
verifichi una delle suddette condizioni e la proprieta e stata verificata direttamente. 

Eof viene comunemente verificata in una condizione di ciclo, per controllare 
l'elaborazione in sequenza di tutti i record di un dataset. Se viene aperto un dataset 
contenente record (o se viene chiamato First) Eofe false. Per elaborare tutti record nel 
dataset uno per volta, creare un ciclo che si sposti di record in record chiamando il 
metodo Next e che termini quando Eofe impostato a true. Eo/rimarra false fino al 
momento in cui Next verra chiamato quando il cursore e gia sull'ultimo record. 

II seguente codice illustra un modo per impostare un ciclo di elaborazione dei record 
per un dataset denominato CustTable: 

CustTable->DisableControls ( ) ; 
try 

{ 

for (CustTable->First(); !CustTable->Eof ; CustTable->Next ( ) ) 
( 

// Process each record here 

} 

} 

__finally 

{ 

CustTable->EnableControls ( ) ; 

} 

Questo esempio dimostra anche come disabilitare e abilitare i controlli visuali 
associati ai dati correlati a un dataset. Disabilitando i controlli visuali durante 
l'iterazione, l'elaborazione risulta piu rapida, in quanto l'applicazione non ha 
bisogno di aggiornare il contenuto dei controlli quando il record corrente cambia. Al 
completamento dell'iterazione, e opportuno abilitare nuovamente i controlli per 
aggiornarli con i valori della nuova riga corrente. Si tenga presente che l'attivazione 
dei controlli visuali avviene nella clausola finally di un'istruzione try... finally. 



22-8 Guida alia programmazione 



Spostamenti nei dataset 



Questo assicura che, anche se un'eccezione pone fine prematuramente 
all'elaborazione del ciclo, i controlli non rimangano disabilitati. 

Bof 

Quando Bofe true, indica che il cursore e posizionato inequivocabilmente sulla prima 
riga di un dataset. Bofe true quando un'applicazione 

• Apre un dataset. 

• Chiama il metodo First di un dataset. 

• Chiama il metodo Prior di un dataset e il metodo non riesce a compiere alcuna 
operazione (perche il cursore si trova alia prima riga del dataset). 

• Chiama SetRange su un intervallo o dataset vuoto. 

Bofe false in tutti gli altri casi; si deve presupporre che Bof sia false, a meno che si 
verifichi una delle suddette condizioni e la proprieta e stata verificata direttamente. 

Come Eof Bof pub essere inserita in una condizione di ciclo per controllare 
l'elaborazione in sequenza dei record di un dataset. II seguente codice illustra un 
modo per impostare un ciclo di elaborazione dei record per un dataset denominato 

CustTable: 

CustTable->DisableControls ( ) ; // Speed up processing; prevent screen flicker 
try 

{ 

while ( !CustTable->Bof ) // Cycle until Bof is true 
( 

// Process each record here 
CustTable->Prior() ; 

// Bof false on success; Bof true when Prior fails on first record 

} 

} 

__finally 

{ 

CustTable->EnableControls ( ) ; 

} 

Contrassegno e ritorno ai record 



Oltre che spostarsi da un record al successivo (o impostare un numero specifico di 
record per lo spostamento), in un dataset e sovente utile contrassegnare un punto 
specifico di un dataset, per potervi accedere direttamente quando si desidera. 
TDataSet introduce una funzione di bookmark composta da una proprieta Bookmark 
e da cinque metodi di bookmark. 

TDataSet implementa metodi segnalibro virtual. Anche se questi metodi assicurano 
che qualsiasi oggetto dataset derivato da TDataSet restituisca un valore se viene 
chiamato un metodo segnalibro, i valori di ritorno sono semplici valori predefiniti 
che non tengono traccia della posizione attuale. I discendenti di TDataSet si 
differenziano per il livello di supporto fornito per i segnalibri. Nessuno dei dataset 
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dbExpress offre un supporto per i segnalibri. I dataset ADO possono supportare i 
segnalibri, a seconda delle tabelle di database sottostanti. I dataset BDE, dataset 
InterBase express e i dataset client supportano sempre i segnalibri. 

La proprieta Bookmark 

La proprieta Bookmark indica quale segnalibro tra un qualsiasi numero di segnalibri 
dell'applicazione e quello corrente. Bookmark e una stringa che identifica il segnalibro 
attuale.Ogni volta che si aggiunge un altro segnalibro, questo diviene il segnalibro 
corrente. 

II metodo GetBookmark 

Per creare un segnalibro, e necessario dichiarare nell'applicazione una variabile di 
tipo TBookmark e chiamare quindi GetBookmark per allocare un'area di memoria per la 
variabile e impostarne il valore a una posizione specifica del dataset. La variabile di 
tipo TBookmark e un puntatore (void *). 

I metodi GotoBookmark e BookmarkValid 

Quando riceve un segnalibro, GotoBookmark sposta il cursore del dataset alia 
posizione specificata nel segnalibro. Prima di chiamare GotoBookmark si puo chiamare 
BookmarkValid per determinare se il segnalibro punta a un record. BookmarkValid 
restituisce true se il segnalibro specificato punta a un record. 

II metodo CompareBookmarks 

Si puo chiamare CompareBookmarks anche per vedere se un segnalibro al quale ci si 
desidera muovere e diverso da un altro (o da quello corrente). Se i due segnalibri 
fanno riferimento alio stesso record (o se entrambi sono NULL), CompareBookmarks 
restituisce 0. 

II metodo FreeBookmark 

FreeBookmark libera la memoria assegnata a un determinato segnalibro, quando 
quest'ultimo non serve piu. E opportuno chiamare FreeBookmark prima di riutilizzare 
un segnalibro esistente. 

Un esempio di utilizzo dei segnalibri 

II seguente codice illustra un impiego dei segnalibri: 

void DoSomething (const TTable *Tbl) 

{ 

TBookmark Bookmark = Tbl->GetBookmark ( ) ; // Allocate memory and assign a value 

Tbl->DisableControls () ; // Turn off display of records in data controls 

try 

{ 

for (Tbl->First () ; !Tbl->Eof; Tbl->Next()) // Iterate through each record in table 
{ 

// Do your processing here 

} 

} 
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finally 

{ 

Tbl->GotoBookmark (Bookmark) ; 

Tbl->EnableControls ( ) ; // Turn on display of records in data controls 
Tbl->FreeBookmark(Bookmark) ; // Deallocate memory for the bookmark 

} 

} 

Prima di passare in sequenza tutti i record, i controlli vengono disabilitati. Qualora si 

verifichi un errore durante l'iterazione tra i record, la clausola finally garantisce 

che i controlli vengano sempre abilitati e che il segnalibro sia sempre liberato anche 
se il ciclo termina prematuramente. 

Ricerche nei dataset 



Se un dataset non e unidirezionale, e possibile effettuare ricerche su di esso 
utilizzando i metodi Locate e Lookup. Questi metodi permettono di ricercare su 
qualsiasi tipo di colonne in qualsiasi dataset. 

TDataSet introducono una famiglia aggiuntiva di metodi per effettuare ricerche in 
base a un indice. Per informazioni su questi metodi aggiuntivi, vedere "Utilizzo di 
indici per la ricerca di record" a pagina 22-29. 

Uso di Locate 



Locate posiziona il cursore sulla prima riga corrispondente a un insieme specificato di 
criteri di ricerca. Nella forma piu semplice, a Locate viene passato il nome di una 
colonna in cui eseguire la ricerca, un valore di campo che rappresenta il criterio di 
ricerca e un flag di opzioni che specifica se la ricerca deve differenziare i caratteri 
maiuscoli e minuscoli o se e valida la corrispondenza parziale alle chiavi. (La 
corrispondenza parziale delle chiavi si verifica quando la stringa di criterio e uguale 
al valore iniziale del valore del campo). Ad esempio, il seguente codice sposta il 
cursore alia prima riga di CustTable, dove il valore della colonna Company e 
"Professional Divers, Ltd.": 

TLocateOptions SearchOptions; 
SearchOptions . Clear () ; 
SearchOptions « loPartialKey ; 

bool LocateSuccess = CustTable->Locate( "Company", "Professional Divers, Ltd.", 
SearchOptions) ; 

Se Locate trova una corrispondenza, il primo record contenente la corrispondenza 
diventa il record corrente. Locate restituisce true se trova un record corrispondente, 
false se non ne trova. Se non vengono trovate corrispondenze, il record corrente non 
cambia. 

La vera potenza di Locate puo essere apprezzata quando si desidera effettuare 
ricerche su piu colonne e specificare valori multipli da cercare. I valori da cercare 
sono Variant, pertanto e possibile specificare tipi di dati diversi nei criteri di ricerca. 
Per specificare piu colonne in una stringa di ricerca, separare le singole voci della 
stringa con un punto e virgola. 
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Poiche i valori da cercare sono Variant, se si passano piu valori e necessario o passare 
come argomento un array Variant (per esempio, i valori restituiti dal metodo 
Lookup), oppure occorre costruire nel codice l'array Variant utilizzando la funzione 
VarArrayOf. II seguente codice illustra una ricerca eseguita su piu colonne, adottando 
valori di ricerca multipli e accettando la corrispondenza parziale alle chiavi: 

TLocateOptions Opts; 

Opts. Clear)) ; 

Opts « loPartialKey; 

Variant locvalues [2] ; 

locvalues [0] = Variant ("Sight Diver"); 

locvalues[l] = Variant ("P") ; 

CustTable->Locate("Company;Contact", VarArrayOf (locvalues, 1), Opts); 

Locate adotta il metodo piu veloce possibile per trovare i record corrispondenti. Se le 
colonne in cui effettuare la ricerca sono indicizzate e l'indice e compatibile con le 
opzioni di ricerca specificate, Locate utilizza l'indice. 

Uso di Lookup 



Lookup cerca la prima riga corrispondente ai criteri di ricerca specificati. Se trova una 
riga corrispondente, determina la rielaborazione dei campi calcolati e dei campi di 
ricerca associati al dataset, quindi restituisce uno o piu campi tratti dalla riga 
corrispondente. Lookup non sposta il cursore sulla riga corrispondente, ma restituisce 
solo valori estratti da essa. 

Nella forma piu semplice, a Lookup viene passato il nome del campo in cui eseguire la 
ricerca, il valore di campo che rappresenta il criterio di ricerca e il campo o i campi da 
restituire. Per esempio, il seguente codice cerca il primo record di CustTable in cui il 
valore del campo Company sia "Professional Divers, Ltd." e restituisce il nome 
dell'azienda, la persona da contattare e il numero di telefono dell'azienda: 

Variant LookupResults = CustTable->Lookup( "Company", "Professional Divers, Ltd", 
"Company;Contact;Phone") ; 

Lookup restituisce i valori per i campi specificati dal primo record corrispondente che 
trova. I valori vengono restituiti come Variant. Se viene richiesto piu di un valore, 
Lookup restituisce un array Variant. Se non esiste alcun record corrispondente, Lookup 
restituisce un Variant Null. Per maggiori informazioni sugli array Variant, consultare 
la Guida in linea. 

La vera potenza di Lookup entra in gioco quando si vogliono effettuare ricerche su piu 
colonne e si specificano piu valori da cercare. Per specificare stringhe contenenti piu 
colonne o campi risultato, separare i singoli campi degli elementi della stringa con 
dei punti e virgola. 

Poiche i valori da cercare sono Variant, se si passano piu valori e necessario o passare 
come argomento un array Variant (per esempio, i valori restituiti dal metodo Lookup), 
oppure occorre costruire nel codice l'array Variant utilizzando la funzione 
VarArrayOf. II codice seguente illustra una ricerca di lookup su piu colonne: 

Variant LookupResults; 
Variant locvalues [2] ; 
Variant v; 
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locvalues[0] = Variant ("Sight Diver"); 
locvalues[l] = Variant ("Kato Paphos"); 

LookupResults = CustTable->Lookup("Company;City", VarArrayOf (locvalues, 1), 

"Company; Addrl ; Addr2 ; State ; Zip" ) ; 
// now put the results in a global stringlist (created elsewhere) 
pFieldValues->Clear ( ) ; 

for (int 1 = 0; i < 5; i++) // Lookup call requested 5 fields 

{ 

v = LookupResults. GetElement (i) ; 
if (v.IsNullO) 

pFieldValues->Add("") ; 
else 

pFieldValues->Add(v) ; 

} 

Come Locate, Lookup adotta il metodo piu veloce possibile per trovare i record 
corrispondenti. Se le colonne in cui effettuare la ricerca sono indicizzate, Lookup 
utilizza l'indice. 

Visualizzazione e modifica di un sottoinsieme di dati usando i filtri 



Spesso un'applicazione e interessata solo a un sottoinsieme di record di un dataset. 
Per esempio, puo essere necessario reperire o visualizzare solo i record relativi alle 
aziende con sede in un determinate Paese nel database dei clienti, oppure puo servire 
solo un record contenente un insieme specifico di valori di campi. In ciascun caso, e 
possibile usare filtri per restringere l'accesso di un'applicazione a un sottoinsieme di 
tutti i record del dataset. 

Con i dataset unidirezionali, e possibile ridurre i record nel dataset solo se si specifica 
una query che limita il numero di record nel dataset. Con altri discendenti di 
TDataSet, tuttavia, e possibile definire un sottoinsieme dei dati che sono gia stati 
prelevati. Per limitare l'accesso di un'applicazione a un sottoinsieme di tutti i record 
nel dataset, e possibile utilizzare filtri. 

Un filtro specifica le condizioni che un record deve soddisfare per essere 
visualizzato. Le condizioni del filtro possono essere stipulate nella proprieta Filter di 
un dataset o possono essere codificate nel suo gestore di evento OnFilterRecord. Le 
condizioni del filtro sono basate sui valori di un qualunque numero di campi di un 
dataset, siano essi indicizzati o meno. Ad esempio, per visualizzare solamente i 
record relativi alle aziende con sede in California, un semplice filtro richiederebbe 
che i record contengano il valore "CA" nel campo State. 

I filtri valgono per ogni record reperito in un dataset. Quando devono essere filtrati 
volumi ingenti di dati, invece di utilizzare i filtri puo essere piu efficace ricorrere a 
una query per limitare il reperimento dei record, oppure impostare un intervallo in 
una tabella indicizzata. 

Attivazione e disattivazione dei filtri 



L'attivazione dei filtri su un dataset e un processo in tre fasi: 
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1 Creazione di un filtro. 

2 Impostazione, se occorre, delle opzioni per i filtri basati su stringhe. 

3 Impostazione della proprieta Filtered a true. 

Quando il filtro e attivo, solamente i record che ne soddisf ano i criteri sono 
disponibili a un'applicazione. II filtro e sempre una condizione provvisoria. II filtro 
puo essere disattivato impostando la proprieta Filtered a false. 

Creazione di filtri 



Ci sono due modi per creare un filtro per un dataset: 

• Specificare semplici condizioni di filtro nella proprieta Filter. Filter e 
particolarmente utile per creare e applicare filtri in fase di esecuzione. 

• Scrivere un gestore di evento OnFilterRecord per condizioni del filtro semplici o 
complesse. Con OnFilterRecord, si specificano in fase di progetto le condizioni di 
filtro. A differenza della proprieta Filter, che e limitata a una singola stringa che 
contiene la logica del filtro, un evento OnFilterRecord puo sfruttare salti 
condizionali e cicli per creare complesse condizioni di filtro multi-livello. 

II vantaggio principale di creare filtri usando la proprieta Filter e che un'applicazione 
puo creare, modificare e applicare dinamicamente filtri, (per esempio, in risposta a 
un input dell'utente). Lo svantaggio principale consiste nel fatto che le condizioni del 
filtro devono essere esprimibili in una singola stringa di testo, non si puo far uso di 
costrutti di diramazione condizionale o ciclici, e non e possibile verificare o 
confrontare valori con valori che non siano gia presenti nel dataset. 

I vantaggi dell'evento OnFilterRecord sono che un filtro puo essere complesso e 
variabile, puo essere basato su molte righe di codice che usano strutture condizionali 
e cicliche, e puo confrontare valori del dataset con valori esterni al dataset, come ad 
esempio il testo in una casella di testo. II principale punto debole di OnFilterRecord e 
che si imposta il filtro in fase di progetto e quindi non puo essere cambiato in risposta 
a un input dell'utente. (E comunque possibile creare molti gestori di filtro e passare 
dall'uno all'altro in risposta alle condizioni generali di un'applicazione). 

Le sezioni che seguono descrivono come creare filtri usando la proprieta Filter e il 
gestore di evento OnFilterRecord. 

Impostazione della proprieta Filter 

Per creare un filtro usando la proprieta Filter, impostare il valore della proprieta a 
una stringa che contiene le condizioni del filtro. L'istruzione che segue, ad esempio, 
crea un filtro che verifica se il campo State di un dataset contiene un valore per lo 
stato della California: 

Datasetl->Filter = "State = 'CA'*; 

E anche possibile fornire un valore a Filter in base al testo immesso in un controllo. 
L'istruzione che segue, ad esempio, assegna a Filter il testo di una casella di testo: 

Datasetl->Filter = Editl->Text; 
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Owiamente, e possibile creare una stringa basata su un testo inserito a livello di 
codice e sui dati immessi dall'utente: 

Datasetl->Filter = AnsiString( "State = "') + Editl->Text + 

I valori dei campi vuoti non vengono visualizzati a meno che non siano inclusi 
esplicitamente nel filtro: 

Datasetl->Filter = "State <> 'CA' or State = BLANK" ; 

Dopo aver specificato un valore di Filter, si imposti a true la proprieta Filtered per 
applicare il filtro al dataset. 

I filtri possono confrontare i valori dei campi con letterali e costanti usando i seguenti 
operatori logici e di confronto: 

Tabella 22.4 Operatori logici e di confronto che possono apparire in un filtro 
Operatore Significato 

< Minore di 

> Maggiore di 

>= Maggiore o uguale a 

<= Minore o uguale a 

Uguale a 

<> Non uguale a 

AND Verifica che due istruzioni siano entrambe true 

NOT Verifica che l'istruzione seguente non sia true 

OR Verifica che almeno uno delle due istruzioni sia true 

+ Aggiunge numeri, concatena stringhe, aggiunge numeri a valori data/ora 

(disponibile solo per alcuni driver) 

Sottrae numeri, sottrae date o sottrae un numero da una data (disponibile solo per 
alcuni driver) 

* Moltiplica due numeri (disponibile solo per alcuni driver) 
/ Divide due numeri (disponibile solo per alcuni driver) 

* carattere jolly per confronti parziali (FilterOptions deve includere 
foPartialCompare) 

Usando combinazioni di questi operatori, e possibile creare filtri abbastanza 
sofisticati. L'istruzione che segue, ad esempio, si assicura che le due condizioni di 
verifica siano soddisfatte prima di accettare un record da visualizzare: 

(Custno > 1400) AND (Custno < 1500); 

Quando il filtro e attivato, le modifiche apportate da un utente a un record possono 
determinare che quest'ultimo non corrisponda piu alle condizioni verificate dal filtro. 
Al successivo reperimento del record nel dataset, il record puo dunque "scomparire". 
In questo caso, il record successivo che passa la condizione di filtro diventa il record 
corrente. 
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Scrittura di un gestore di eventi OnFilterRecord 

Per indicare se un record soddisfa la condizione di filtro, il gestore di evento 
OnFilterRecord imposta il parametro Accept a true per includere un record o a false 
per escluderlo. Per esempio, il seguente filtro visualizza solo i record con il campo 
State impostato su "CA". 

void __fastcall TForml: :TablelFilterRecord(TDataSet *DataSet; bool &Accept) 
{ 

Accept = DataSet->FieldByName[ "State" ]->AsString == "CA"; 

} 

Quando il filtro e attivo, per ciascun record reperito viene generato un evento 
OnFilterRecord. II gestore di evento verifica ciascun record e visualizza solamente 
quelli che soddisfano le condizioni del filtro. Poiche l'evento OnFilterRecord viene 
generato per ogni record di un dataset, il codice del gestore di evento dovrebbe 
essere il piu breve possibile per evitare che influenzi negativamente le prestazioni 
dell'applicazione. 

Commutazione dei gestori evento di filtro in esecuzione 

E possibile programmare un numero qualsiasi di gestori evento OnFilterRecord e 
passare dall'uno all'altro in fase di esecuzione. Le istruzioni che seguono, ad 
esempio, passano a un gestore di evento OnFilterRecord, chiamato NewYorkFilter. 

DataSetl->OnFilterRecord = NewYorkFilter; 
Refresh) ) ; 

Impostazione delle opzioni del filtro 



La proprieta Filter Options consente di specificare se un filtro che confronta campi 
basati su stringhe accetta i record in base a un confronto parziale e se il confronto 
delle stringhe deve tener conto delle maiuscole/minuscole. Filter Options e una 
proprieta set che puo essere un set vuoto (impostazione predefinita), o che puo 
contenere l'uno o l'altro o entrambi i seguenti valori: 

Tabella 22.5 Valori di FilterOptions 
Valore Significato 

foCaselnsensitive Ignora maiuscolo/ minuscolo durante il confronto delle stringhe. 

foNoPartialCompare Disattiva la corrispondenza parziale di stringa; vale a dire che le stringhe 
che terminano con un asterisco (*) non vengono confrontate. 



Le istruzioni che seguono, ad esempio, prepararono un filtro che, durante il 
confronto dei valori nel campo State, non tiene conto delle maiuscole/minuscole: 

TFilterOptions FilterOptions; 
FilterOptions->Clear() ; 
FilterOptions « foCaselnsensitive; 
Tablel->FilterOptions = FilterOptions; 
Tablel->Filter = "State = 'CA 1 "; 
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Spostamento tra i record in un dataset filtrato 



Esistono quattro metodi del dataset che consentono di spostarsi tra i record di un 
dataset filtrato. La tabella che segue elenca questi metodi e descrive cio che fanno: 



Tabella 22.6 Metodi di navigazione nei dataset filtrati 
Metodo Scopo 



FindFirst Si sposta al primo record che corrisponde al criterio di filtro corrente. La ricerca 

del primo record corrispondente comincia sempre dal primo record del dataset 
non filtrato. 

FindLast Si muove all'ultimo record che corrisponde al criterio di filtro corrente. 

FindNext Si sposta dal record attuale del dataset filtrato al successivo. 

FindPrior Si sposta dal record corrente del dataset filtrato a quello precedente. 

L'istruzione che segue, ad esempio, trova il primo record filtrato di un dataset: 

DataSetl->FindFirst () ; 

Purche si imposti la proprieta Filter o si crei un gestore di evento OnFilterRecord per 
un'applicazione, questi metodi posizionano il cursore sul record specificato 
indipendentemente dal fatto che il filtraggio si attivo o meno. Se si chiamano questi 
metodi quando il filtro non e attivo 

• Attivano temporaneamente il filtro. 

• Posizionano il cursore su un record corrispondente, se ne viene trovato uno. 

• Disattivano il filtro. 

Se il filtro e disattivato e non si imposta la proprieta Filter o si crea un gestore di 
evento OnFilterRecord, questi metodi non fanno alcunche di diverso da FirstO, Last(), 
Next() e Priori). 

Tutti i metodi filtro di spostamento posizionano il cursore su un record 
corrispondente, se ne e stato trovato uno, rendendolo il record attivo, e restituiscono 
true. Se non si trova un record corrispondente, la posizione del cursore rimane 
immutata e questi metodi restituiscono false. E possibile controllare lo stato della 
proprieta Found per inglobare queste chiamate, ed eseguire un'azione solo quando 
Found e true. Se, ad esempio, il cursore e gia sull'ultimo record corrispondente del 
dataset e si chiama FindNext, il metodo restituisce false e il record corrente non 
cambia. 



Modifica dei dati 



E possibile utilizzare i metodi del dataset sotto elencati per inserire, aggiornare e 
cancellare dati se la proprieta a sola lettura CanModify e true. CanModify e true a 
meno che il dataset non sia unidirezionale, che il database sottostante al dataset non 
consenta i diritti di lettura e di scrittura o non intervengano altri fattori. (Questi 
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fattori includono la proprieta ReadOnly di alcuni dataset o la proprieta RequestLive dei 
componenti TQuery). 



Tabella 22.7 Metodi dei dataset per inserire, aggiornare e cancellare dati 




Edit Imposta il dataset in modalita dsEdit, se gia non e nello stato dsEdit o dslnsert. 

Append Invia i dati in attesa, sposta il record attivo alia fine del dataset e pone il dataset in 
modalita dslnsert. 



Insert Invia i dati in attesa e pone il dataset in modalita dslnsert. 

Post Cerca di registrare nel database il record nuovo o modificato. Se 1'operazione riesce, 

il dataset torna alio stato dsBrowse; se non riesce, il dataset rimane nello stato 
corrente. 

Cancel Annulla 1'operazione corrente e pone il dataset in modalita dsBrowse. 

Delete Cancella il record corrente e pone il dataset in modalita dsBrowse. 



Modifica dei record 



Un dataset deve essere in modalita dsEdit perche un'applicazione possa modificare i 
record. Nel codice, il metodo Edit puo essere utilizzato per impostare un dataset in 
modalita dsEdit se la proprieta a sola lettura CanModify del dataset e true. 

Quando un dataset passa in modalita dsEdit, riceve dapprima un evento BeforeEdit. 
Dopo il passaggio alia modalita editing, il dataset riceve un evento AfterEdit. Di 
solito, questi eventi sono utilizzati per l'aggiornamento deH'interfaccia utente per 
indicare lo stato corrente del dataset. Se il dataset non puo essere posto in modalita 
editing per un qualche motivo, si verifica un evento OnEditError, in cui e possibile 
informare l'utente del problema o provare a correggere la situazione che ha impedito 
al dataset di passare in modalita editing. 

Nelle schede dell'applicazione, alcuni controlli associati ai dati possono portare 
automaticamente un dataset alio stato dsEdit se 

• La proprieta ReadOnly del controllo e false (impostazione predefinita), 

• La proprieta AutoEdit del datasource e true e 

• CanModify e true per il dataset. 

Anche se un dataset e nello stato dsEdit, la modifica dei record puo non riuscire per i 
database basati su SQL se l'utente dell'applicazione non possiede i privilegi di 
accesso SQL appropriati. 

Quando un dataset e in modalita dsEdit, un utente puo modificare i valori dei campi 
del record corrente che appaiono nei controlli associati ai dati di una scheda. I 
controlli associati ai dati per i quali la modifica e consentita chiamano 
automaticamente Post quando un utente esegue un'operazione che cambia il record 
corrente (per esempio lo spostamento a un altro record in una griglia). 

Se nelle schede e previsto un componente Navigator, gli utenti possono annullare le 
modifiche facendo clic sul pulsante Cancel del Navigator. Annullando le modifiche, 
viene ripristinato lo stato dsBrowse del dataset. 




22-18 Guida alia programmazione 



Modifica dei dati 

Nel codice, e necessario scrivere o annullare le modifiche chiamando i metodi 
appropriati. Le modifiche vengono scritte chiamando Post. Possono essere annullate 
chiamando Cancel. Nel codice, Edit e Post sono sovente utilizzati insieme. Per 
esempio, 

Tablel->Edit () ; 

Tablel->FieldValues["CustNo"] = 1234; 
Tablel->Post () ; 

Nell'esempio precedente, la prima riga di codice imposta la modalita dsEdit per il 
dataset. La successiva riga di codice assegna la stringa "1234" al campo CustNo del 
record corrente. Infine, l'ultima riga scrive, ovvero registra, il record modificato nel 
database. Se non si utilizzano gli aggiornamenti in cache, la registrazione scrive le 
modifiche nel database di origine. Se si utilizzano gli aggiornamenti in cache, la 
modifica vengono scritte in un buffer temporaneo, in cui restano finche non viene 
chiamato il metodo ApplyUpdates del dataset. 

Aggiunta di nuovi record 



Un dataset deve essere in modalita dslnsert perche un'applicazione possa 
aggiungervi nuovi record. Nel codice, e possibile utilizzare i metodi Insert o Append 
per portare un dataset in modalita dslnsert, a patto che la proprieta a sola lettura 
CanModify del dataset sia true. 

Quando un dataset passa in modalita dslnsert, riceve dapprima un evento 
Beforelnsert. Dopo che il completamento con successo del passaggio alia modalita 
inserimento, il dataset riceve prima un evento OnNewRecord e quindi un evento 
Afterlnsert. E possibile usare questi eventi, ad esempio, per fornire dei valori iniziali 
per i record appena inseriti: 

void __fastcall TForml: :OrdersTableNewRecord(TDataSet *DataSet) 

{ 

DataSet->FieldByName("OrderDate")->AsDateTime = Dated; 

} 

Nelle schede dell'applicazione, i controlli griglia data-awar e Navigator possono 
impostare un dataset in stato dslnsert se 

• La proprieta ReadOnly del controllo e false (impostazione predefinita) e 

• CanModify e true per il dataset. 

Anche se un dataset e nello stato dslnsert, l'aggiunta di record puo non andare a buon 
fine per i database basati su SQL nel caso l'utente dell'applicazione non abbia i 
privilegi di accesso SQL appropriati. 

Quando un dataset e in modalita dslnsert, un utente o un'applicazione puo immettere 
valori nei campi associati al nuovo record. Ad eccezione dei controlli griglia e 
Navigator, non esistono differenze visibili a un utente tra Insert e Append. Chiamando 
Insert, nella griglia appare una riga vuota sopra quello che era il record corrente. 
Chiamando Append, la griglia viene fatta scorrere fino all'ultimo record del dataset, 
appare una riga vuota nella parte inferiore della griglia e i pulsanti Next e Last 
vengono disattivati in qualsiasi componente Navigator associato al dataset. 
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I controlli data-aware per i quali e consentito l'inserimento chiamano 
automaticamente Post quando un utente esegue un'operazione che cambia il record 
corrente (per esempio lo spostamento a un altro record in una griglia). In caso 
contrario, Post deve essere chiamato nel codice. 

Post scrive il nuovo record nel database oppure, se sono abilitati gli aggiornamenti in 
cache, Post scrive il record in una cache in memoria. Per scrivere nel database gli 
inserimenti e le aggiunte in cache, chiamare il metodo ApplyUpdates del dataset. 

Inserimento di record 

Insert apre un nuovo record vuoto prima del record corrente e imposta il record 
vuoto come record corrente, cosicche l'utente o il codice dell'applicazione possa 
immettervi valori di campi. 

Quando un'applicazione chiama Post (o ApplyUpdates se gli aggiornamenti in cache 
sono consentiti), un record appena inserito puo essere scritto nel database in tre 
modi: 

• Per le tabelle Paradox e dBASE indicizzate, il record viene inserito nel dataset in 
una posizione basata sul relativo indice. 

• Per le tabelle Paradox e dBASE non indicizzate, il record viene inserito nel dataset 
nella posizione corrente. 

• Per i database SQL, il punto di inserimento fisico dipende dall'implementazione. 
Se la tabella e indicizzata, l'indice viene aggiornato con le informazioni del nuovo 
record. 

Aggiunta di record 

Append apre un nuovo record vuoto alia fine del dataset e lo imposta come record 
corrente, cosicche un utente o il codice dell'applicazione possa immettervi valori di 
campi. 

Quando un'applicazione chiama Post (o ApplyUpdates se gli aggiornamenti in cache 
sono consentiti), un record appena inserito puo essere scritto nel database in tre 
modi: 

• Per le tabelle Paradox e dBASE indicizzate, il record viene inserito nel dataset in 
una posizione basata sul relativo indice. 

• Per le tabelle Paradox e dBASE non indicizzate, il record viene aggiunto alia fine 
del dataset. 

• Per i database SQL, il punto fisico in cui awiene l'aggiunta dipende 
dall'applicazione. Se la tabella e indicizzata, l'indice viene aggiornato con le 
informazioni del nuovo record. 

Cancellazione dei record 



Utilizzare il metodo Delete per cancellare il record corrente in un dataset attivo. 
Quando si chiama il metodo Delete, 
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• II dataset riceve un evento BeforeDelete. 

• II dataset tenta di cancellare il record corrente. 

• II dataset ritorna alio stato dsBrowse. 

• II dataset riceve un eventoAfterDelete. 

Se si vuole evitare la cancellazione nel gestore di evento BeforeDelete, si puo chiamare 
la procedura globale Abort: 

void __fastcall TForml: :TableBeforeDelete (TDataSet *Dataset) 
{ 

if (MessageBoxfO, "Delete This Record?", "CONFIRM" , MB_YESN0) != IDYES) 
Abort ( ) ; 

} 

Se Delete non va a buon fine, genera un evento OnDeleteError. Se il gestore di evento 
OnDeleteError non puo risolvere il problema, il dataset rimane nello stato dsEdit. Se 
Delete va a buon fine, il dataset ritorno alio stato dsBrowse e il record successivo a 
quello cancellato diventa il record corrente. 

Se si utilizzano gli aggironamenti in cache, il record cancellato non viene rimosso 
dalla tabella di database sottostante finche non si chiama Applyllpdates. 

Se nelle schede e previsto un componente navigator, gli utenti possono cancellare il 
record corrente facendo clic sul pulsante Delete del Navigator. Nel codice, e 
necessario chiamare esplicitamente Delete per rimuovere il record corrente. 

Registrazione dei dati 



Dopo avere finito di modificare un record, e necessario chiamare il metodo Post per 
scrivere le modifiche. II metodo Post si comporta in modo diverso, a seconda dello 
stato del dataset e del fatto che si stiano utilizzando gli aggiornamenti in cache. 

• Se non si utilizzano gli aggiornamenti in cache e il dataset e nello stato dsEdit o 
dslnsert, Post scrive il record corrente nel database e riporta il dataset alio stato 

dsBrowse. 

• Se si utilizzano gli aggiornamenti in cache e il dataset e nello stato dsEdit o dslnsert, 
Post scrive il record corrente in una cache interna e riporta il dataset alio stato 
dsBrowse. Le modifiche non vengono scritto nel database finche non si chiama 
Applyllpdates. 

• Se il dataset e in modalita dsSetKey, Post riporta il dataset alio stato dsBrowse. 

Indipendentemente dallo stato iniziale del dataset, Post genera eventi BeforePost e 
AfterPost, prima e dopo aver scritto le modifiche correnti. E possibile utilizzare questi 
eventi per aggiornare l'interfaccia utente o impedire al dataset registrare le modifiche 
chiamando la procedura Abort. Se la chiamata a Post non riesce, il dataset riceve un 
evento OnPostError, dove e possibile informare l'utente del problema o tentare di 
correggerlo. 

La registrazione puo essere effettuata esplicitamente o implicitamente nell'ambito di 
un'altra procedura. Quando un'applicazione si sposta dal record corrente, Post viene 
chiamato implicitamente. Le chiamate ai metodi First, Next, Prior e Last eseguono 
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un'operazione Post se la tabella e in modalita dsEdit o dslnsert. Anche i metodi Append 
e Insert registrano implicitamente i dati in sospeso. 

II metodo Close non chiama implicitamente Post. Per registrare in modo esplicito 
qualsiasi modifica in sospeso, occorre usare l'evento BeforeClose. 

Annullamento delle modifiche 



Un'applicazione puo annullare in qualsiasi momento le modifiche apportate al 
record corrente, se non ha ancora chiamato direttamente o indirettamente Post. Per 
esempio, se un dataset e in modalita dsEdit e un utente modifica i dati di uno o piu 
campi, l'applicazione puo ripristinare i valori originali del record chiamando il 
metodo Cancel del dataset. Una chiamata a Cancel riporta sempre il dataset alio stato 
dsBrowse. 

Se nel momento in cui l'applicazione ha chiamato Cancel il dataset era in modo dsEdit 
o dslnsert, il dataset riceve gli eventi BeforeCancel e AfterCancel prima e dopo che il 
record corrente e stato ripristinato ai suoi valori originali. 

Nelle schede, e possibile consentire agli utenti di annullare le operazioni di modifica, 
inserimento o aggiunta includendo un pulsante Cancel in un componente Navigator 
associato al dataset, oppure e possibile specificare il codice del pulsante Cancel nella 
scheda. 

Modifica di interi record 



Nelle schede, tutti i controlli associati ai dati, ad eccezione dei controlli griglia e 
Navigator, forniscono l'accesso a un unico campo di un record. 

Tuttavia nel codice e possibile adottare i seguenti metodi che funzionano con intere 
strutture di record, purche la struttura delle tabelle di database associate al dataset 
sia stabile e non cambi. La seguente tabella riepiloga i metodi disponibili per lavorare 
con interi record invece che con i singoli campi interni: 

Tabella 22.8 Metodi che funzionano con interi record 
Metodo 

AppendRecord([ariay of values]) 
InsertRecord([anay of values]) 
SetFields([array of values]) 



Questi metodi accettano come argomento un array di valori, in cui ciascun valore 
corrisponde a una colonna nel dataset sottostante. Per creare questi array, si deve 
usare la macro ARRAYOFCONST. I valori possono essere letterali, variabili o NULL. 
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Descrizlone 

Aggiunge un record con i valori di colonna specificati alia fine 
di una tabella; e analogo ad Append. Esegue un'operazione Post 
implicita. 

Inserisce i valori specificati come record prima della posizione 
corrente del cursore in una tabella; e analogo a Insert. Esegue 
un'operazione Post implicita. 

Imposta i valori dei campi corrispondenti; e analogo 
all'assegnazione dei valori a TFields. L'applicazione deve 
eseguire un'operazione Post esplicita. 



Modifica dei dati 



Se il numero di valori di un argomento e inferiore al numero di colonne di un dataset, 
i valori rimanenti sono considerati NULL. 

Per i dataset non indicizzati, AppendRecord aggiunge un record alia fine del dataset, 
mentre InsertRecord inserisce un record dopo la posizione corrente del cursore. Per le 
tabelle indicizzate, entrambi i metodi inseriscono il record nella tabella alia posizione 
corretta, in base all'indice. In entrambi i casi, i metodi spostano il cursore alia 
posizione del record. 

SetFields assegna i valori specificati nell'array di parametri ai campi del dataset. Per 
utilizzare SetFields, un'applicazione deve innanzi tutto chiamare Edit per portare il 
dataset in modalita dsEdit. Per applicare le modifiche al record corrente, deve 
eseguire un'operazione Post. 

Se si usa SetFields per modificare alcuni campi di un record esistente, ma non tutti, e 
possibile passare valori NULL per i campi che non devono essere modificati. Se non 
vengono forniti abbastanza valori per tutti i campi di un record, SetFields assegna ad 
essi valori NULL. I valori NULL sovrascrivono tutti i valori gia esistenti in quei 
campi. 

Ad esempio, si supponga che un database abbia una tabella COUNTRY contenenti le 
colonne Name, Capital, Continent, Area e Population. Se un componente TTable 
denominato CountryTable fosse collegato alia tabella COUNTRY, la seguente 
istruzione inserirebbe un record nella tabella COUNTRY: 

CountryTable->InsertRecord(ARRAYOFCONST( ("Japan", "Tokyo", "Asia") ) ) ; 

Questa istruzione non specifica valori per Area e Population, pertanto in 
corrispondenza di tali campi vengono inseriti valori NULL. La tabella e indicizzata 
in base a Name, quindi l'istruzione inserirebbe il record in base alia collazione 
alfabetica di "Japan". 

Per aggiornare il record, un'applicazione potrebbe usare il seguente codice: 

TLocateOptions SearchOptions; 
SearchOptions->Clear() ; 
SearchOptions « loCaselnsensitive; 

if (CountryTable->Locate("Name", "Japan", SearchOptions)) 

{ 

CountryTable->Edit () ; 

CountryTable->SetFields(ARRAYOFCONST(((void *)NJLL, (void *)NULL, (void *)NULL, 

344567, 164700000))); 
CountryTable->Post () ; 

} 

Questo codice assegna i valori ai campi Area e Population e quindi li registra nel 
database. I tre puntatori NULL si comportano come segnaposto per le prime tre 
colonne, in modo da preservarne il contenuto attuale. 

Quando si usano puntatori NULL con SetFields per lasciare inalterati alcuni valori di 
campo, bisogna accertarsi di effettuare la conversione da NULL a puntatore void *. 
Se si usa NULL come parametro senza effettuare la conversione di tipo, il campo 
verra impostato ad un valore vuoto. 



I dataset 22-23 



Calcolo dei campi 

Calcolo dei campi 



Utilizzando Fields editor, e possibile definire dei campi calcolati per i dataset. 
Quando un dataset contiene campi calcolati, si deve preparare del codice per 
calcolare quei valori di campo in un gestore di evento OnCalcFields. Per ulteriori 
informazioni sulla definizione dei campi calcolati con l'editor Fields, consultare 
"Definizione di un campo calcolato" a pagina 23-7. 

La proprieta AutoCalcFields determina quando OnCalcFields viene chiamato. Se 
AutoCalcFields e true, OnCalcFields viene chiamato quando 

• Un dataset viene aperto. 

• II dataset passa in modalita editing. 

• Un record viene reperito nel database. 

• II fuoco si sposta da un componente visivo a un altro o da una colonna a un'altra 
in un controllo di griglia associata ai dati e il record attivo e stato modificato. 

Se AutoCalcFields e false, OnCalcFields non viene chiamato quando si modificano 
singoli campi all'intemo di un record (la quarta condizione vista in precedenza). 



OnCalcFields viene chiamato frequentemente, quindi il codice scritto per esso deve 
essere breve. Inoltre, se AutoCalcFields e true, OnCalcFields non deve svolgere 
operazioni che modificano il dataset (o un dataset collegato nel caso appartienga a 
una relazione master/ detail), in quanto cio questo pud dar luogo a ricorsivita. Per 
esempio, se OnCalcFields esegue un'operazione Post e AutoCalcFields e true, 
OnCalcFields viene chiamato nuovamente, dando origine a un'altra operazione Post, e 
cosi via. 

Quando viene eseguito OnCalcFields, il dataset passa in modalita dsCalcFields. Questo 
stato impedisce modifiche o aggiunte ai record di un dataset, ad eccezione dei campi 
calcolati che il gestore e previsto possa modificare. II motivo per prevenire altre 
modifiche e dovuto al fatto che OnCalcFields utilizza i valori contenuti in altri campi 
per derivare i valori dei campi calcolati. Eventuali modifiche a questi altri campi, 
potrebbero invalidare i valori assegnati ai campi calcolati. Dopo il completamento di 
OnCalcFields, il dataset torna alio stato dsBrowse. 



Tipi di dataset 



"Utilizzo dei discendenti di TDataSet" a pagina 22-2 classifica i discendenti di 
TDataSet in base al metodo che essi utilizzano per accedere ai propri dati. Un altro 
metodo utile per classificare i discendenti di TDataSet e quello di considerare il tipo 
di server dati che essi rappresentano. In base a quest'ottica, ci sono tre classi di base 
di dataset: 

• Datasets di tipo tabella: I dataset di tipo tabella rappresentano una singola tabella 
di un server di database, comprese tutte le sue righe e colonne. $$$$1 dataset di 
tipo tabella includono TTable, TADOTable, TSQLTable e TIBTable. 
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I dataset di tipo tabella permettono di sfruttare indici definiti sul server. Poiche c'e 
una corrispondenza biunivoca tra tabella di database e dataset, e possibile 
utilizzare gli indici server definiti per la tabella di database. Gli indici permettono 
all'applicazione di ordinare i record nella tabella, di velocizzare ricerche e 
consultazioni e possono costituire la base di una relazione master/detail. Inoltre, 
alcuni dataset di tipo tabella sfruttano il vantaggio della relazione uno-a-uno 
esistente tra il dataset e la tabella di database per permettere di eseguire 
operazioni a livello di tabella, come la creazione e la cancellazione di tabelle di 
database. 

• Dataset di tipo query : I dataset di tipo query rappresentano un singolo comando 
SQL o una query. Le query possono rappresentare il set risultato derivante 
dall'esecuzione di un comando (di solito un'istruzione SELECT) o possono 
eseguire un comando che non restituisce alcun record (ad esempio, un'istruzione 
UPDATE). I dataset di tipo query includono TQuery, TADOQuery, TSQLQuery e 
TIBQuery. 

Per utilizzare un dataset di tipo query, e necessario avere familiarita con SQL e con 
l'implementazione SQL del server, compresi eventuali limiti ed estensioni 
ampliamenti alio standard SQL-92. Se non si ha padronanza di SQL, potrebbe 
valer la pena acquistare un manuale tecnico che tratti SQL in dettaglio. Uno dei 
migliori e Understanding the New SQL: A Complete Guide, di Jim Melton e Alan R. 
Simpson, edito da Morgan Kaufmann. 

• Dataset di tipo procedura registrata: I dataset di tipo procedura registrata 
rappresentano una procedura registrata sul server di database. I dataset di tipo 
procedura registrata includono TStoredProc, TADOStoredProc, TSQLStoredProc e 
TIBStoredProc. 

Una procedura registrata e un programma indipendente scritto nella linguaggio di 
procedure e trigger specifici del sistema di database utilizzato. Di solito 
gestiscono operazioni relative al database ripetute di frequente, e risultano 
particolarmente utili per operazioni che agiscono su grandi quantita di record o 
che utilizzano funzioni di aggregazione o matematiche. Di solito l'utilizzo di 
procedure registrate migliora le prestazioni di un'applicazione database: 

• Sfruttando l'enorme potenza e velocita di elaborazione tipiche dei server. 

• Riducendo il traffico di rete perche tutte le elaborazioni vengono spostate sul 
server. 

Le procedure registrate possono restituire o meno dei dati. Quelle che 
restituiscono dati possono restituirli come un cursor (in modo analogo al risultato 
di una query SELECT), come piu cursor (restituendo in effetti piu dataset) o 
restituire dati nei parametri di output. Queste differenze dipendono in parte dal 
server: alcuni server non permettono alle procedure registrate di restituire dati o 
permettono solo parametri di output. Altri server invece non supportano affatto le 
procedure registrate. Per determinare cosa e possibile fare, consultare la 
documentazione del server. 

Solitamente e possibile utilizzare un dataset di tipo query per eseguire procedure 
registrate poiche la maggior parte dei server dispone di estensioni a SQL per operare 
con le procedure registrate. Ogni server, tuttavia, utilizza a questo scopo la propria 
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sintassi. Se si sceglie di utilizzare un dataset di tipo query invece di un dataset di tipo 
procedura registrata, consultare la documentazione del server per la sintassi 
necessaria. 

Oltre ai dataset che rientrano chiaramente in queste tre categorie, TDataSet ha alcuni 
discendenti che possono essere considerati appartententi a piu di una categoria: 

• TADODataSet e TSQLDataSet hanno una proprieta CommandType che permette di 
specificare se rappresentano una tabella, una query o una procedura registrata. I 
nomi delle proprieta e dei metodo sono molto simili a quelli dei dataset di tipo 
query, benche TADODataSet permetta di specificare un indice come un dataset di 
tipo tabella. 

• TClientDataSet rappresenta i dati da un altro dataset. Come tale, puo rappresentare 
una tabella, una query o una procedura registrata. TClientDataSet si comporta in 
modo molto simile a un dataset di tipo tabella, a causa del suo supporto per gli 
indici. Tuttavia, anche ha alcune delle funzioni dei dataset di tipo query e 
procedura registrata: la gestione dei parametri e la capacita di essere eseguito 
senza acquisire un set risultato. 

• Alcuni altri dataset client (TBDEClientDataSet e TSQLClientDataSet) hanno una 
proprieta CommandType che permette di specificare se essi rappresentano una 
tabella, una query o una procedura registrata. I nomi delle proprieta e dei metodi 
sono come quelli di TClientDataSet, e gli somiglia anche per il supporto dei 
parametri e degli indici e la capacita la capacita di essere eseguito senza acquisire 
un set risultato. 

• TIBDataSet puo rappresentare sia le query che le procedure registrate. Infatti, puo 
rappresentare piu query e procedure registrate contemporaneamente, con 
proprieta separate per ognuno. 

Utilizzo dei dataset di tipo tabella 



Per utilizzare un dataset di tipo tabella, 

1 Collocare il componente dataset appropriato in un modulo dati o su una scheda e 
impostarne la proprieta Name a un valore univoco, consono all'applicazione. 

2 Identificare il server di database che contiene la tabella che si vuole usare. Ogni 
dataset di tipo tabella lo compie in modo diverso, ma di solito si specifica un 
componente database connection: 

• Per TTable, specificare un componente TDatabase o un alias BDE utilizzando la 
proprieta DatabaseName. 

• Per TADOTable, specificare un componente TADOConnection utilizzando la 
proprieta Connection. 

• Per TSQLTable, specificare un componente TSQLConnection utilizzando la 
proprieta SQLConnection. 

• Per TIBTable, specificare un componente TIBConnection utilizzando la proprieta 

Database. 
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Per informazioni sull'utilizzo di component! database connection, vedere il 
Capitolo 21 Capitolo 21, "Connessione ai database". 

3 Impostare la proprieta al nome della tabella nel database. E possibile selezionare le 
tabelle da una lista a discesa se si e gia identificato un componente database 
connection. 

4 Mettere un componente datasource nel modulo dati o sulla scheda e impostarne la 
proprieta DataSet al nome del dataset. II componente datasource viene usato per 
passare un set risultato dal dataset ai componenti data-aware affinche siano 
visualizzati. 

Vantaggi dell'utilizzo dei dataset di tipo tabella 



II vantaggio principale dell'utilizzo di dataset di tipo tabella e la disponibilita di 
indici. Gli indici consentono all'applicazione di 

• Ordinare i record nel dataset. 

• Individuare rapidamente i records. 

• Limitare i record visibili. 

• Stabilire relazioni master / detail. 

Inoltre, la relazione uno-a-uno tra dataset di tipo tabella e tabelle di database 
permette di utilizzare molti di loro per i seguenti scopi 

• Controllo dell'accesso alle tabelle in lettura/scrittura 

• Creazione e cancellazione di tabelle 

• Svuotamento di tabelle 

• Sincronizzazione di tabelle 

Ordinamento dei record con indici 



Un indice determina l'ordine di visualizzazione dei record in una tabella. Di solito, i 
record vengono visualizzati in ordine ascendente in base a un indice primario o 
predefinito. Questo comportamento predefinito non richiede intervento da parte 
dell'applicazione. Se si desidera una sequenza di ordinamento diversa, tuttavia, e 
necessario specificare 

• Un indice alternativo, oppure. 

• Una lista di colonne su cui ordinare (non disponibile su server che non sono basati 
su SQL). 

Gli indici permettono di presentare i dati da una tabella secondo diversi ordinamenti. 
Su tabelle basate su SQL, questa sequenza di ordinamento e implementata 
utilizzando l'indice per generare una clausola ORDER BY in una query che preleva i 
record della tabella. Su altre tabelle (come tabelle Paradox e dBASE), l'indice e 
utilizzato dal meccanismo di accesso di dati per presentare i record nell'ordine 
richiesto. 
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Ottenimento di informazioni sugli indici 

L'applicazione puo ottenere informazioni su indici definiti dal server da tutti i 
dataset di tipo tabella. Per ottenere una lista degli indici disponibili per il dataset, 
chiamare il metodo GetlndexName. GetlndexNames riempie una lista di stringhe con i 
nomi degli indici validi. Ad esempio, il seguente codice riempie una casella di 
riepilogo con i nomi di tutti gli indici definiti per il dataset Customer sT able: 
CustomersTable->GetIndexNames (ListBoxl->Items) ; 

Nel caso di tabelle Paradox, l'indice principale e senza nome e non viene quindi 
restituito da GetlndexNames. Con una tabella Paradox, comunque, e sempre possibile 
reimpostare l'indice in uso all'indice principale, dopo avere utilizzato un indice 
alternativo, impostando la proprieta IndexName a una stringa vuota. 

Per ottenere informazioni sui campi dell'indice corrente, utilizzare 

• La proprieta IndexFieldCount, per determinare il numero di colonne nell'indice. 

• La proprieta IndexFields, per esaminare una lista dei componenti campo per le 
colonne che comprendono l'indice. 

II codice seguente mostra come si protrebbero utilizzare IndexFieldCount e IndexFields 
per passare in sequenza una lista di nomi di colonna in un'applicazione: 

AnsiString ListOf IndexFields [20] ; 

for (int 1 = 0; i < CustomersTable->IndexFieldCount; i++) 
ListOf IndexFields [i] = CustomersTable->lndexFields [i] ->FieldName; 

IndexFieldCount non e valido per una tabella dBASE aperta in base a un indice di 
espressione. 

Specifica di un indice con IndexName 

Per fare in modo che un indice diventi attivo, utilizzare la proprieta IndexName. Una 
volta attivo, un indice determina l'ordine dei record nel dataset. (Puo essere 
utilizzato anche come base per un collegamento master-detail, per una ricerca basata 
su indice o per un filtraggio basato su indice). 

Per attivare un indice, impostare la proprieta IndexName al nome di un indice. In 
alcuni sistemi di database, gli indici principali non hanno nomi. Per attivare uno di 
questi indici, impostare IndexName a una stringa vuota. 

In progettazione, e possibile selezionare un indice da una lista di indici disponibili 
facendo clic nell'Object Inspector sul pulsante ellissi della proprieta. In fase di 
esecuzione, impostare IndexName utilizzando una costante o una variabile AnsiString. 
E possibie ottenere una lista degli indici disponibili chiamando il metodo 

GetlndexName. 

II seguente codice imposta l'indice per Customer sF able a CustDescending: 

CustomersTable->lndexName = "CustDescending"; 

Creazione di un indice con IndexFieldNames 

Se non c'e alcun indice definito che implementa la sequenza di ordinamento 
desiderata, e possibile creare uno pseudo-indice utilizzando la proprieta 

IndexFieldNames. 
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IndexName and IndexFieldNames sono reciprocamente esclusivi. L'impostazione della 
proprieta di uno cancella i valori impostati per l'altro. 

II valore di IndexFieldNames e una stringa ansi. Per specificare una sequenza di 
ordinamento, elencare ogni nome di colonna da utilizzare nell'ordine che dovrebbe 
essere utilizzato e delimitare i nomi con punti e virgola. L'ordinamento e solo 
ascendente. La dipendenza dell'ordinamento dalle maiuscole e legata alle capacita 
del server. Per ulteriori informazioni, vedere la documentazione del server. 

II seguente codice imposta la sequenza di ordinamento per PhoneTable in base a 
LastName, quindi a FirstName: 

PhoneTable->IndexFieldNames = "LastName;FirstName" ; 

Se si utilizza IndexFieldNames su tabelle Paradox e dBASE, il dataset tenta di trovare 
un indice che utilizza le colonne specificate. Se non e in grado di trovare un tale 
indice, solleva un'eccezione. 



Utilizzo di indici per la ricerca di record 



Si puo effettuare una ricerca in un qualsiasi dataset usando i metodi Locate e Lookup 
di TDataSet. Comunque, se si utilizzano esplicitamente gli indici, alcuni dataset di 
tipo tabella possono migliorare di molto le prestazioni di una ricerca fornite dai 
metodi Locate e Lookup. 

I dataset ADO supportano tutti il metodo Seek, che sposta a un record in base a un 
insieme di valori di campo per i campi nell'indice corrente. Seek permette di 
specificare dove spostare il cursore rispetto al primo o all'ultimo record 
corrispondente. 

TTable e tutti i tipi di dataset client supportano ricerche simili basate su indici, ma 
utilizzano una combinazione di metodi collegati. La seguente tabella riassume i sei 
metodi collegati forniti da TTable e dai dataset client per supportare le ricerche basate 
su indice: 



Tabella 22.9 Metodi di ricerca basati sugli indici 
Metodo Scopo 

EditKey Preserva il contenuto corrente del buffer della chiave di ricerca e pone il dataset 

nello stato dsSetKey in modo che l'applicazione possa modificare i criteri di 
ricerca esistenti prima dell'esecuzione di una ricerca. 

FindKey Combina in un singolo metodo i metodi SetKey e GotoKey. 

FindNearest Combina in un singolo metodo i metodi SetKey e GotoNearest. 

GotoKey Ricerca il primo record in un dataset che corrisponde esattamente ai criteri di 

ricerca e, nel caso lo trovi, sposta il cursore su quel record. 

GotoNearest Ricerca, in base a un valore di chiave parziale, nei campi basati su stringhe la 
corrispondenza piu simile a un record e sposta il cursore a quel record. 

SetKey Cancella il buffer della chiave di ricerca e pone la tabella nello stato dsSetKey in 

modo che l'applicazione possa specificare nuovi criteri di ricerca prima di 
eseguire una ricerca. 
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GotoKey e FindKey sono funzioni boolean che, se vanno a buon fine, spostano il 
cursore a un record corrispondente e restituiscono true. Se la ricerca non va a buon 
fine, il cursore non viene spostato e queste funzioni restituiscono false. 

GotoNearest e FindNearest ricollocano sempre il cursore o sulla prima corrispondenza 
esatta trovata o, nel caso non venga trovata alcuna corrispondenza, sul primo record 
che e maggiore dei criteri di ricerca specificati. 

Esecuzione di una ricerca con metodi Goto 

Per eseguire una ricerca utilizzando i metodi Goto, seguire questi passi generali: 

1 Specificare l'indice da utilizzare per la ricerca. Questo e lo stesso indice che ordina 
i record nel dataset (vedere "Ordinamento dei record con indici" a pagina 22-27). 
Per specificare l'indice, utilizzare la proprieta IndexName o IndexFieldNames. 

2 Aprire il dataset. 

3 Porre il dataset nello stato dsSetKey chiamando SetKey. 

4 Specificare il valore o i valori da ricercare nella proprieta Fields. Fields e un oggetto 
TFields, che gestisce una lista indicizzata di componenti campo, a cui e possibile 
accedere specificando il numero ordinale che corrisponde alia colonna. II primo 
numero di colonna in un dataset e 0. 

5 Cercare e spostarsi al primo record corrispondente trovato con GotoKey o con 
GotoNearest. 

Ad esempio, il codice seguente, collegato all'evento OnClick di un pulsante, utilizza il 
metodo GotoKey per spostarsi al primo record in cui il primo campo nell'indice ha un 
valore che corrisponde esattamente al testo immesso in una casella di testo: 

void __fastcall TSearchDemo: :SearchExactClick(TObject *Sender) 
{ 

ClientDataSetl->SetKey ( ) ; 

ClientDataSetl->Fields->Fields[0]->AsString = Editl->Text; 
if (!ClientDataSetl->GotoKey() ) 
ShowMessage( "Record not found"); 

} 

GotoNearest e simile. Cerca la corrispondenza piu vicina a un valore parziale di un 
campo. Puo essere utilizzato solo per campi stringa. Per esempio, 

Tablel->SetKey() ; 

Tablel->Fields->Fields[0]->AsString = "Sm"; 
Tablel->GotoNearest() ; 

Se esiste un record che contiene "Sm" come primi due caratteri del valore del primo 
campo indicizzato, il cursore viene posizionato su quel record. Altrimenti, la 
posizione del cursore non cambia e GotoNearest restituisce false. 

Esecuzione di una ricerca con metodi Find 

I metodi Find fanno la stessa cosa dei metodi Goto, salvo che non e necessario porre 
esplicitamente il dataset nello stato dsSetKey per specificare i valori del campo chiave 
su cui effettuare la ricerca. Per eseguire una ricerca utilizzando i metodi Find, seguire 
questi passi generali: 



22-30 Guida alia programmazione 



Utilizzo dei dataset di tipo tabella 

1 Specificare l'indice da utilizzare per la ricerca. Questo e lo stesso indice che ordina 
i record nel dataset (vedere "Ordinamento dei record con indici" a pagina 22-27). 
Per specificare l'indice, utilizzare la proprieta IndexName o IndexFieldNames. 

2 Aprire il dataset. 

3 Ricercare e spostarsi al primo record, o a quello piu vicino, con FindKey o con 
FindNearest. Entrambi i metodi richiedono un singolo parametro, una lista di 
valori di campo, delimitata con virgole, in cui ogni valore corrisponde a una 
colonna indicizzata della tabella sottostante. 

FindNearest pud essere utilizzato solo per campi stringa. 

Specifica del record corrente dopo una ricerca andata a buon fine 

Per impostazione predefinita, una ricerca che va a buon fine posiziona il cursore sul 
primo record che corrisponde ai criteri di ricerca. Se si preferisce, e possibile 
impostare la proprieta KeyExclusive a true in modo da posizionare il cursore sul 
record immediatamente successivo al primo record corrispondente. 

Per impostazione predefinita, KeyExclusive e false, vale a dire che una ricerca andata 
a buon fine posiziona il cursore sul primo record corrispondente. 

Ricerca in base a chiavi parziali 

Se un dataset client ha piu di una colonna chiave e si vuole effettuare una ricerca per 
valori in un sottoinsieme di quella chiave, impostare KeyFieldCount al numero di 
colonne su cui si sta facendo la ricerca. Ad esempio, se l'indice corrente del dataset 
client ha tre colonne e si vogliono cercare dei valori utilizzando solo la prima 
colonna, impostare KeyFieldCount a 1. 

Nel caso di dataset ditpo tabella con chiavi su piu colonne, e possibile cercare i valori 
solo in colonne contigue, iniziando dalla prima. Ad esempio, per una chiave 
composta da tre colonne e possibile cercare i valori nella prima colonna, nella prima e 
nella seconda o nella prima, seconda e terza ma non solo nella prima e nella terza. 

Ripetizione o ampliamento di una ricerca 

Ogni volta che si chiamano SetKey o FindKey, il metodo azzera qualsiasi valore 
precedente nella proprieta Fields. Se si desidera ripetere una ricerca utilizzando i 
campi impostati in precedenza o si desidera fare un'aggiunta ai campi utilizzati in 
una ricerca, chiamare EditKey invece di SetKey e di FindKey. 

Ad esempio, si supponga di aver gia eseguita una ricerca nella tabella Employee in 
base al campo City dell'indice "Citylndex". Si supponga inoltre che "Citylndex" 
includa anche i campi City e Company. Per trovare un record con un determinate) 
nome di azienda in una determinata citta, utilizzare il seguente codice: 

Employee->KeyFieldCount = 2; 
Employee->EditKey ( ) ; 

Employee->FieldValues ["Company"] = Variant (Edit2->Text) ; 
Employee->GotoNearest ( ) ; 
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Limitazione dei record con gli intervalli 



E possibile vedere e modificare temporaneamente un sottoinsieme di dati di qualsiasi 
dataset usando i filtri (consultare "Visualizzazione e modifica di un sottoinsieme di 
dati usando i filtri" a pagina 22-13). Alcuni dataset di tipo tabella supportano anche 
un altro modo per accedere a un sottoinsieme dei record disponibili, detto intervalli. 

Gli intervalli sono utilizzabili sono con TTable e con i dataset client. Malgrado le loro 
somiglianze, gli intervalli e i filtri hanno utilizzi differenti. I paragrafi seguenti 
descrivono le differenze fra intervalli e filtri e spiegano come utilizzare gli intervalli. 

Differenze fra intervalli e filtri 

Sia gli intervalli che i filtri limitano i record visibili a un sottoinsieme di tutti i record 
disponibili, ma il loro modo di operare e diverso. Un intervallo e un insieme di 
record indicizzati in contiguo che sono compresi entro valori limite specif icati. Ad 
esempio, in un database di dipendenti indicizzato in base al cognome, si potrebbe 
applicare un intervallo per visualizzare tutti i dipendenti i cui cognomi sono 
maggiori di "Jones" e minori di "Smith". Poiche gli intervalli dipendono dagli indici, 
e necessario impostare come indice corrente quello che puo essere utilizzato per 
definire l'intervallo. Analogamente alia specifica di un indice per ordinare i record, 
utilizzando la proprieta IndexName oppure IndexFieldNames e possibile assegnare 
l'indice in base a cui definire un intervallo. 

Un filtro, invece, e un qualunque insieme di record che condividono dei punti dati 
specificati, indipendentemente dalla loro indicizzazione. Ad esempio, si potrebbe 
filtrare un database di dipendenti per visualizzare tutti i dipendenti che vivono in 
California e che hanno lavorato per la societa per cinque o piu anni. Benche i filtri 
possono fare uso di indici nel caso siano disponibili, i filtri non dipendono dagli 
indici. I filtri vengono applicati record per record mentre un'applicazione esamina in 
sequenza un dataset. 

Di solito, i filtri sono piu flessibili degli intervalli. Gli intervalli, tuttavia, possono 
essere piu efficienti quando si opera con dataset molto grandi e i record che 
interessano a un'applicazione sono gia bloccati in gruppi indicizzati in modo 
contiguo. Per dataset molto grandi, potrebbe risultare ancora piu efficiente l'utilizzo 
della clausola WHERE di un dataset di tipo query per selezionare i dati. Per i dettagli 
sulla specifica di una query, vedere "Utilizzo di dataset di tipo query" a pagina 22-43. 

Specifica degli intervalli 

Esistono due modi reciprocamente esclusivi per specificare un intervallo: 

• Specificare l'inizio e la fine utilizzando separatamente SetRangeStart e 
SetRangeEnd. 

• Specificare entrambi i punti terminali in una sola volta utilizzando SetRange. 

Impostazione del l'inizio di un intervallo 

Chiamare la procedura SetRangeStart per porre il dataset nello stato dsSetKey e 
iniziare a creare una lista di valori iniziali per l'intervallo. Una volta che si chiama 
SetRangeStart, le successive assegnazioni alia proprieta Fields sono trattate come 
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valori iniziali dell'indice da utilizzare nell'applicazione dell'intervallo. I campi 
specificati devono essere inclusi nell'indice corrente. 

Ad esempio, si supponga che l'applicazione utilizzi un componente 
TSQLCHentDataSet di nome Customers, collegato con la tabella CUSTOMER e che 
siano stati creati dei componenti campo persistenti per ogni campo nel dataset 
Customers. CUSTOMER e indicizzato sulla prima colonna (CustNo). Una finestra 
dell'applicazione consente di modificare due componenti di nome StartVal e EndVal, 
utilizzati per specificare il valore iniziale e finale di un intervallo. Per creare e 
applicare un intervallo si pud utilizzare il seguente codice: 

Customers->SetRangeStart ( ) ; 

Customers->FieldValues ["CustNo"] = StrToInt (StartVal->Text ) ; 
Customers->SetRangeEnd( ) ; 
if ( !EndVal->Text.IsEmpty() ) 

Customers->FieldValues ["CustNo"] = StrToInt (EndVal->Text ) ; 
Customers->ApplyRange ( ) ; 

Prima di assegnare un qualsiasi valore a Fields, questo codice controlla che il testo 
immesso in EndVal non sia nullo. Se il testo immesso per StartVal e nullo, allora 
vengono inclusi tutti i record dall'inizio del dataset, perche tutti i valori sono 
maggiori di zero. Tuttavia, se il testo immesso per EndVal e nullo, allora non viene 
incluso nessun record, perche nessun record e minore di nullo. 

Nel caso di un indice su piu colonne, e possibile specificare un valore iniziale per tutti 
o per alcuni campi nell'indice. Se non si fornisce il valore di un campo usato 
nell'indice, quando si applica l'intervallo viene assunto un valore nullo. Se si prova a 
impostare un valore per un campo che non e incluso nell'indice, il dataset solleva 
un'eccezione. 

Per partire daU'inizio del dataset, omettere la chiamata a SetRangeStart. 

Per terminare di specificare l'inizio di un intervallo, chiamare SetRangeEnd oppure 
applicare o annullare l'intervallo. Per informazioni sull'applicazione e 
l'annullamento di intervalli, consultare "Applicazione o annullamento di un 
intervallo" a pagina 22-36. 

Impostazione del la fine di un intervallo 

Chiamare la procedura SetRangeEnd per mettere il dataset nello stato dsSetKey e 
cominciare a creare una lista di valori finali per l'intervallo. Una volta chiamata 
SetRangeEnd, le successive assegnazioni alia proprieta Fields vengono trattate come 
valori finali di indice da usare quando si applichera l'intervallo. I campi specificati 
devono essere inclusi nell'indice corrente. 

Occorre specificare sempre i valori finali di un intervallo, anche se si vuole che 
l'intervallo finisca all'ultimo record del dataset. Se non si forniscono valori finali, 
C++Builder presuppone che il valore finale dell'intervallo sia un valore nullo. Un 
intervallo con valori finali nulli e sempre vuoto. 

II modo piu facile per assegnare i valori finali e quello di chiamare il metodo 
FieldByName method. Per esempio, 

Contacts->SetRangeStart ( ) ; 

Contacts->FieldByName ( "LastName" ) ->Value = Editl->Text; 
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Contacts->SetRangeEnd( ) ; 

Contacts->FieldByName ( "LastName" ) ->Value = Edit2->Text; 
Contacts->ApplyRange ( ) ; 

Come per la specifica dei valori iniziali dell'intervallo, se si prova a impostare tin 
valore per un campo che non e incluso nell'indice, il dataset solleva un'eccezione. 

Per terminare di specificare la fine di un intervallo, applicare o annullare l'intervallo. 
Per informazioni sull'applicazione e rannullamento di intervalli, consultare 
"Applicazione o annullamento di un intervallo" a pagina 22-36. 



Impostazione del valore iniziale e finale di un intervallo 

Invece di utilizzare chiamate separate a SetRangeStart e a SetRangeEnd per specificare 
i limiti dell'intervallo, e possibile chiamare la procedura SetRange per porre il dataset 
nello stato dsSetKey e impostare i valori iniziali e finali di un intervallo con una 
singola chiamata. 

SetRange richiede due parametri constant array: una serie di valori iniziali e una serie 
di valori finali. Le istruzioni seguenti, ad esempio, stabiliscono un intervallo basato 
su un indice a due colonne: 

TVarRec StartVals[2] ; 
TVarRec EndVals[2] ; 
StartVals[0] = Editl->Text; 
StartVals[l] = Edit2->Text; 
EndVals[0] = Edit3->Text; 
EndVals[l] = Edit4->Text; 

Tablel->SetRange(StartVals, 1, EndVals, 1); 

Nel caso di un indice su piu colonne e possibile specificare i valori di inizio e di fine 
per tutti i campi dell'indice o solo per alcuni di essi. Se non si fornisce il valore di un 
campo usato nell'indice, quando si applica l'intervallo viene assunto un valore nullo. 
Per omettere un valore per il primo campo in un indice e specificare dei valori per i 
campi consecutivi, passare un valore nullo per il campo omesso. 

Occorre specificare sempre i valori finali di un intervallo, anche se si vuole che 
l'intervallo finisca all'ultimo record del dataset. Se non si forniscono valori finali, il 
dataset presuppone che il valore finale dell'intervallo sia un valore nullo. Un 
intervallo con valori finali nulli e sempre vuoto perche l'intervallo iniziale e 
maggiore o uguale all'intervallo finale. 



Specifica di un intervallo in base a chiavi parziali 

Se una chiave e composta da uno o piu campi di tipo stringa, i metodi SetRange 
supportano chiavi parziali. Se, ad esempio, un indice e basato sulle colonne LastName 
e FirstName, le seguenti specifiche di intervallo risultano valide: 



Contacts->SetRangeStart ( ) ; 
Contacts->FieldValues ["LastName"] = "Smith"; 
Contacts->SetRangeEnd( ) ; 

Contacts->FieldValues ["LastName"] = "Zzzzzz"; 
Contacts->ApplyRange ( ) ; 
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Questo codice include tutti i record in un intervallo in cui LastName e maggiore o 
uguale a "Smith". La specifica del valore potrebbe anche essere: 

Contacts->FieldValues ["LastName"] = "Sm"; 

Questa istruzione include i record in cui LastName e maggiore o uguale a "Sm". 

Inclusione o esclusione dei record che corrispondono ai limiti dell'intervallo 

Per impostazione predefinita, un intervallo include tutti i record maggiori o uguali al 
valore di inizio intervallo e minori o uguali al valore di fine intervallo specificati. 
Questo comportamento e controllato dalla proprieta KeyExclusive. Per impostazione 
predefinita KeyExclusive e false. 

Se si preferisce, e possibile impostare la proprieta KeyExclusive di un dataset a true in 
modo da escludere i record uguali al valore di fine intervallo. Ad esempio, 

Contacts->SetRangeStart ( ) ; 
Contacts->KeyExclusive = true; 
Contacts->FieldValues ["LastName"] = "Smith"; 
Contacts->SetRangeEnd( ) ; 
Contacts->FieldValues ["LastName"] = "Tyler"; 
Contacts->ApplyRange ( ) ; 

Questo codice include tutti i record in un intervallo in cui LastName e maggiore o 
uguale a "Smith" e minore di "Tyler". 

Modifica di un intervallo 

Due funzioni permettono di modificare le condizioni esistenti dei limiti estremi di un 
intervallo: EditRangeStart, per modificare i valori iniziali di un intervallo; ed 
EditRangeEnd, per modificare i valori finali dell'intervallo. 

II processo per modificare e applicare un intervallo implica questi passi generali: 

1 Porre il dataset nello stato dsSetKey e modificare il valore iniziale dell'indice 
dell'intervallo. 

2 Modifica del valore finale dell'indice dell'intervallo. 

3 Applicare l'intervallo al dataset. 

E possibile modificare o il singolo valore iniziale o finale dell'intervallo, oppure si 
possono modificare entrambe le condizioni dei limiti estremo. Se si modificano le 
condizioni relative ai limiti estremi di un intervallo che e attualmente applicato a un 
dataset, le modifiche apportate non divengono effettive finche non si chiama 
nuovamente ApplyRange. 

Modifica dell'inizio di un intervallo 

Chiamare la procedura EditRangeStart per porre il dataset nello stato dsSetKey e 
iniziare a modificare la lista corrente dei valori iniziali dell'intervallo. Una volta che 
si chiama EditRangeStart, le successive assegnazioni alia proprieta Fields 
sovrascrivono i valori correnti di indice da utilizzare al momento dell'applicazione 
dell'intervallo. 
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(") Se inizialmente si era creato un inizio intervallo in base a una chiave parziale, e 

possibile utilizzare EditRangeStart per ampliare il valore iniziale dell'intervallo. Per 

ulteriori informazioni sugli intervalli basati su chiavi parziali, consultare "Specifica 
di un intervallo in base a chiavi parziali" a pagina 22-34. 

Modifica della fine di un intervallo 

Chiamare la procedura EditRangeEnd per porre il dataset nello stato dsSetKey e 
iniziare a creare una lista di valori finali per l'intervallo. Una volta che si chiama 
EditRangeEnd, le successive assegnazioni alia proprieta Fields sono trattate come 
valori finali dell'indice da utilizzare al momenta dell'applicazione dell'intervallo. 

Applicazione o annullamento di un intervallo 

Quando si chiamano SetRangeStart o EditRangeStart per specificare l'inizio di un 
intervallo, oppure SetRangeEnd o EditRangeEnd per specificare la fine di un intervallo, 
il dataset viene posto nello stato dsSetKey. Esso resta in quello stato finche non si 
applica o non si annulla l'intervallo. 

Applicazione di un intervallo 

Quando si specifica un intervallo, le condizioni di limite che vengono definite non 
diventano effettive finche non si applica l'intervallo. Affinche un intervallo entri in 
vigore, si deve chiamare il metodo ApplyRange. ApplyRange limita immediatamente la 
vista e l'accesso da parte di un utente solo ai dati inclusi nel sottoinsieme specificato 
del dataset. 

Annullamento di un intervallo 

II metodo CancelRange pone fine all'applicazione di un intervallo e ripristina l'accesso 
all'intero dataset. Anche se l'annullamento un intervallo ripristina l'accesso a tutti i 
record nel dataset, le condizioni di limite di quell'intervallo sono ancora disponibili, 
rendendo possibile riapplicare l'intervallo in un momento successivo. I limiti di 
intervallo vengono conservati finche non si forniscono nuovi limiti per intervallo o 
non si modificano i limiti esistenti. Ad esempio, il seguente codice e valido: 

MyTable->CancelRange ( ) ; 

// later on, use the same range again. No need to call SetRangeStart, etc. 
MyTable->ApplyRange ( ) ; 



Creazione di relazioni master/detail 



I dataset di tipo tabella possono essere collegati mediante relazioni master /detail. 
Quando si imposta una relazione master /detail, si collegano due dataset in modo che 
tutti i record di uno (il detail) corrispondono sempre al singolo record attivo 
dell'altro (il master). 

I dataset di tipo tabella supportano le relazioni master/ detail in due modi molto 
diversi: 
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• Tutti i dataset di tipo tabella possono agire come dettaglio di un altro dataset 
mediante il collegamento dei cursor. Questo processo e descritto in 
"Trasformazione della tabella nella tabella dettaglio di un altro dataset". 

• TTable, TSQLTable e tutti i dataset client possono agire come master in una 
relazione di master/ detail che utilizza tabelle dettaglio annidate. Questo processo 
viene descritto nella sezione "Utilizzo di tabelle dettaglio annidate" a 

pagina 22-38. 

Ognuno di questi approcci offre i propri vantaggi. II collegamento di cursor permette 
di creare relazioni master/ detail in cui la tabella principale e un qualsiasi tipo di 
dataset. Con tabelle di dettaglio annidate, i tipi di dataset che possono agire come 
tabella di dettaglio sono limitati, ma offrono molte piu possibility nel modo di 
visualizzare i dati. Se il master e un dataset client, le tabelle dettaglio annidate 
forniscono un meccanismo piu affidabile per applicare gli aggiornamenti in cache. 

Trasformazione della tabella nella tabella dettaglio di un altro dataset 

Le proprieta MasterSource e MasterFields di un dataset di tipo tabella possono essere 
utilizzate per impostare relazioni uno a molti tra due dataset 

La proprieta MasterSource e utilizzata per specificare un datasource da cui la tabella 
ottiene i dati dalla tabella principale. Questo datasource puo essere collegato con 
qualsiasi tipo di dataset. Per esempio, se in questa proprieta si specifica il datasource 
di una query, e possibile collegare un dataset client come dettaglio delle query, in 
modo che il dataset client tracci gli eventi che si verificano nella query. 

II dataset e collegato con la tabella principale in base al suo indice corrente. Prima di 
specificare i campi del dataset principale che vengono tracciati dal dataset di 
dettaglio, specificare per prima cosa l'indice nel dataset di dettaglio che inizia con i 
campi corrispondenti. E possibile utilizzare le proprieta IndexName o 
IndexFieldNames . 

Una volta specificato l'indice da utilizzare, utilizzare la proprieta MasterFields per 
indicare la o le colonne nel dataset principale che corrispondono ai campi dell'indice 
nella tabella di dettaglio). Per collegare dataset in base a piu nomi di colonne, 
separare i nomi dei campi con punti e virgola: 

Parts->MasterFields = "OrderNo;ItemNo"; 

Per aiutare a creare collegamenti significativi tra i due dataset, e possibile utilizzare 
Field Link designer. Per utilizzare Field Link designer, fare doppio clic nell'Object 
Inspector sulla proprieta MasterFields dopo avere assegnato un MasterSource e un 
indice. 

Le istruzioni successive consentono di creare una semplice scheda in cui l'utente puo 
esaminare ad uno ad uno i record dei clienti e visualizzare tutti gli ordini relativi al 
cliente corrente. La tabella master e la tabella Customer sF able e la tabella dettaglio e 
OrdersFable. L' esempio utilizza il componente basato su BDE FFable, ma e possibile 
utilizzare gli stessi metodi per collegare qualsiasi dataset di tipo tabella. 

1 Collocare in un modulo dati due componenti FFable e due componenti 
FDataSource. 

2 Impostare le proprieta del primo componente FFable come segue: 
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• DatabaseName: BCDEMOS 

• TableName: CUSTOMER 

• Name: CustomersTable 

3 Impostare le proprieta del secondo componente TTable come segue: 

• DatabaseName: BCDEMOS 

• TableName: ORDERS 

• Name: OrdersTable 

4 Impostare le proprieta del primo componente TDataSource come segue: 

• Name: CustSource 

• DataSet: CustomersTable 

5 Impostare le proprieta del secondo componente TDataSource come segue: 

• Name: OrdersSource 

• DataSet: OrdersTable 

6 Collocare su una scheda due componenti TDBGrid. 

7 Scegliere l'opzione File I Include Unit Hdr per specificare che la scheda deve 
utilizzare il modulo dati. 

8 Impostare la proprieta DataSource del primo componente griglia a "CustSource", e 
impostare la proprieta DataSource della seconda griglia a "OrdersSource". 

9 Impostare la proprieta MasterSource di OrdersTable a "CustSource". In questo 
modo la tabella CUSTOMER (la tabella principale) e la tabella ORDERS (la tabella 
di dettaglio) risultano collegate. 

10 Fare doppio clic nell'Object Inspector sulla casella del valore della proprieta 
MasterFields in modo da richiamare il Field Link Designer e impostare le seguenti 
proprieta: 

• Nel campo Available Indexes, scegliere CustNo per collegare le due tabelle in 
base al campo CustNo. 

• Selezionare CustNo in entrambe le liste dei campi Detail Fields e Master Fields. 

• Fare clic sul pulsante Add per aggiungere questa condizione di join. Nell'elenco 
Joined Fields, apparira la scritta "CustNo -> CustNo". 

• Scegliere OK per confermare le selezioni e uscire da Field Link Designer. 

11 Impostare le proprieta Active di CustomersTable e OrdersTable a true per 
visualizzare i dati nelle griglie della scheda. 

12 Compilare ed eseguire l'applicazione. 

Se si esegue ora l'applicazione, si potra notare che le tabelle sono collegate e che, 
quando ci si sposta su un nuovo record della tabella CUSTOMER, nella tabella 
ORDERS si vedono solo quei record che appartengono al cliente corrente. 

Utilizzo di tabelle dettaglio annidate 

Una tabella annidata e un dataset dettaglio che e il valore di un singolo campo di 
dataset in un altro dataset (master). Per i dataset che rappresentano dati del server, 
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un dataset dettaglio annidato pud essere utilizzato solo per un campo di dataset sul 
server. I componenti TClientDataSet non rappresentano dati del server, ma, se per 
loro si crea un dataset che contiene dettagli annidati o se ricevono dati da un 
provider collegato con la tabella master di una relazione di master/ detail, possono 
anche contenere campi di dataset. 

Per TClientDataSet, l'uso di set di dettaglio annidati e necessario se si vogliono 
applicare gli aggiornamenti dalle tabelle master e detail al server di database. 

Per utilizzare i set di dettaglio annidati, la proprieta ObjectView del dataset master 
deve essere impostata a true. Quando il dataset di tipo tabella contiene i dataset di 
dettaglio annidati, TDBGrid fornisce il supporto per la visualizzazione dei dettagli 
annidati in una finestra a comparsa. Per ulteriori informazioni sul funzionamento, 
consultare "Visualizzazione dei campi dataset" a pagina 23-27. 

In alternativa, e possibile visualizzare e modificare i dataset di dettaglio in controlli 
associati ai dati utilizzando un componente dataset separato per il set di dettaglio. In 
progettazione, si devono creare campi persistenti per i i campi del dataset (master), 
utilizzando Fields Editor: fare clic destro sul dataset master e scegliere Fields Editor. 
Aggiungere al dataset un nuovo campo esistente facendo clic destro e scegliendo 
Add Fields. Definire il nuovo campo con il tipo DataSet Field. Nel Fields Editor 
definire la struttura della tabella di dettaglio. E necessario anche aggiungere campi 
persistenti per tutti gli altri campi utilizzati nel dataset master. 

II componente dataset per la tabella dettaglio e un discendente di dataset di uno dei 
tipi consentito dalla tabella master. Solo i componenti TTable permettono di usare 
componenti TNestedDataSet come dataset annidati. I componenti TSQLTable 
permettono l'uso di altri componenti TSQLTable. I componenti TClientDataset 
permettono l'uso di altri dataset client. Scegliere nella Component palette un dataset 
di tipo appropriato e aggiungerlo alia scheda o al modulo dati. Impostare la 
proprieta DataSetField di questo dataset di dettaglio al campo persistente DataSet nel 
dataset master. Infine, collocare sulla scheda o sul modulo dati un componente 
datasource e impostarne la proprieta DataSet al dataset dettaglio. I controlli data- 
aware possono utilizzare questo datasource per accedere ai dati nel set di dettaglio. 



Controllo dell'accesso alle tabelle in lettura/scrittura 



Per impostazione predefinita, quando si apre un dataset di tipo tabella, esso richiede 
i diritti di lettura e scrittura per la tabella di database sottostante. A seconda delle 
caratteristiche della tabella di database sottostante, il privilegio di scrittura richiesto 
potrebbe non essere concesso (ad esempio, quando si richiede l'accesso in scrittura a 
una tabella SQL su un server remoto e il server limita l'accesso alia tabella alia sola 
lettura). 

Questo non e vero per TClientDataSet, che determina se gli utenti possono modificare 
i dati provenienti da informazioni che il provider di dataset fornisce mediante 
pacchetti dati. Anche per TSQLTable, che e un dataset unidirezionale e percio sempre 
a sola lettura, non e vero. 

Quando si apre la tabella, e possibile controllare la proprieta CanModify per accertare 
se il database sottostante (o il provider di dataset) permette agli utenti di modificare i 
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dati nella tabella. Se CanModify e false, l'applicazione non puo scrivere nel database. 
Se CanModify e true, l'applicazione puo scrivere nel database a condizione che la 
proprieta ReadOnly della tabella sia false. 

ReadOnly determina se un utente puo sia visualizzare che modificare i dati. Quando 
ReadOnly e false (impostazione predefinita), un utente puo sia vedere sia modificare i 
dati. Per limitare un utente alia sola visualizzazione dei dati, ReadOnly va impostata a 
true prima di aprire una tabella. 

ReadOnly e implementata su tutti i dataset di tipo tabella tranne TSQLTable, che e 
sempre a sola lettura. 

Creazione e cancellazione di tabelle 



Alcuni dataset di tipo tabella permettono di creare e di cancellare le tabelle 
sottostanti in fase di progettazione o di esecuzione. Di solito, le tabelle di database 
vengono create e cancellate da un amministratore di database. Tuttavia, puo essere 
utile durante sviluppo e il collaudo di applicazioni creare e distruggere le tabelle di 
database che l'applicazione puo utilizzare. 

Creazione di tabelle 

TTable e TIBTable permettono entrambi di creare la tabella di database sottostante 
senza utilizzare SQL. Alio stesso modo, TClientDataSet permette di creare un dataset 
quando non si sta operando con un provider di dataset. Utilizzando TTable e 
TClientDataSet, e possibile creare la tabella in progettazione o in esecuzione. Solo 
TIBTable permette di creare tabelle in esecuzione. 

Prima di potere creare la tabella, e necessario aver impostato alcune proprieta per 
specificare la struttura della tabella che si vuole creare. In particolare, e necessario 
specificare: 

• II database che conterra la nuova tabella. Per TTable, si specifica il database 
utilizzando la proprieta DatabaseName. Per TIBTable, e necessario utilizzare un 
componente TIBDatabase, assegnato alia proprieta Database. (I dataset client non 
utilizzano un database). 

• II tipo del database (solo per TTable). Impostare la proprieta TableType al tipo di 
tabella richiesto. Per tabelle Paradox, dBASE o ASCII, impostare rispettivamente 
TableType a ttParadox, a ttDBase o ttASCII.Ver tutti gli altri tipi di tabella, impostare 
TableType a ttDefault. 

• II nome della tabella che si vuole creare. Sia TTable che TIBTable hanno una 
proprieta TableName per il nome della nuova tabella. I dataset client non utilizzano 
un nome della tabella, ma, prima di salvare la nuova tabella, si dovrebbe 
specificare la proprieta FileName. Se si crea una tabella che duplica il nome di una 
tabella esistente, la tabella esistente e tutti i suoi dati saranno sovrascritti dalla 
tabella appena creata. La vecchia tabella e i suoi dati non potranno essere 
recuperati. Per evitare di sovrascrivere una tabella esistente, e possibile controllare 
la proprieta Exists in esecuzione. Exists e disponibile solo per TTable e TIBTable. 

• I campi della nuova tabella. E possibile farlo in due modi: 
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• E possibile aggiungere definizioni di campo alia proprieta FieldDefs. In 
progettazione, fare doppio clic nell'Object Inspector sulla proprieta FieldDefs 
per richiamare il Collection editor. Utilizzare il Collection editor per 
aggiungere, cancellare o modificare le proprieta delle definizioni dei campi. In 
esecuzione, cancellare qualsiasi definizione di campo esistente e quindi 
utilizzare il metodo AddFieldDef per aggiungere ogni nuova definizione di 
campo. Per ogni nuova definizione di campo, impostare le proprieta 
dell'oggetto TFieldDef per specificare gli attributi desiderati per il campo. 

• In alternativa, e possibile utilizzare anche componenti campo persistenti. In 
progettazione, fare doppio clic sul datset per richiamare il Fields editor. Nel 
Fields editor, fare clic destro e scegliere il comando New Field. Descrivere le 
proprieta di base del campo. Una volta creato il campo, e possibile modificarne 
le proprieta nell'Object Inspector selezionando il campo Fields Editor. 

• Gli indici per la nuova tabella (facoltativo).In progettazione, fare doppio clic 
nell'Object Inspector sulla proprieta IndexDefs per richiamare il Collection editor. 
Utilizzare il Collection editor per aggiungere, cancellare o modificare le proprieta 
delle definizioni degli indici. In esecuzione, cancellare qualsiasi definizione di 
indice esistente e quindi utilizzare il metodo AddlndexDef per aggiungere ogni 
nuova definizione di indice. Per ogni nuova definizione di indice, impostare le 
proprieta dell'oggetto TIndexDef per specificare gli attributi desiderati per l'indice. 

E impossibile definire indici per la nuova tabella se si utilizzano componenti campo 
persistenti invece di oggetti di definizione campo. 

Per creare la tabella in progettazione, fare clic destro sul dataset e scegliere Create 
Table (TTable) o Create Data Set (TClientDataSet). Questo comando non viene 
visualizzato nel menu di scelta rapida finche non sono state specificate tutte le 
informazioni necessarie. 

Per creare la tabella in esecuzione, chiamare il metodo CreateTable (TTable e TIBTable) 
o il metodo CreateDataSet (TClientDataSet). 

Per creare la tabella e possibile impostare le definizioni in progettazione e poi 
chiamare il metodo CreateTable (o CreateDataSet) in esecuzione. Tuttavia, per poterlo 
fare e ncessario indicare che le definizioni specificate in progettazione devono essere 
salvate con il componente dataset. (per impostazione predefinita, le definizioni di 
campo e di indice vengono generate dinamicamente in esecuzione). Specificare che 
le definizioni devono essere salvate con il dataset impostando a True la proprieta 
StoreDefs del dataset. 

Se si utilizza TTable, e possibile precaricare in progettazione le definizioni di campo e 
di indice di una tabella esistente. Impostare le proprieta DatabaseName e TableName 
per specificare la tabella esistente. Fare clic destro sul componente tabella e scegliere 
Update Table Definition. In questo modo, i valori delle proprieta FieldDefs e IndexDefs 
vengono impostati automaticamente per descrivere i campi e gli indici della tabella 
esistente. Dopo, reimpostare DatabaseName e TableName per specificare la tabella che 
si desidera creare, annullando qualsiasi richiesta di rinominare la tabella esistente. 

Quando si creano tabelle Oracle8, e impossibile creare campi oggetto (campi ADT, 
campi array e campi dataset). 
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II codice seguente crea una nuova tabella in fase di esecuzione e la associa all'alias 
BCDEMOS. Prima di creare la nuova tabella, verifica che il nome di tabella fornito 
non corrisponda al nome di una tabella esistente: 

TTable *NewTable = new TTable (Forml) ; 
NewTable->Active = false; 
NewTable->DatabaseName = "BCDEMOS"; 
NewTable->TableName = Editl->Text; 
NewTable->TableType = ttDefault; 
NewTable->FieldDefs->Clear() ; 

TFieldDef *NewField = NewTable->FieldDefs->AddFieldDef () ; // define first field 
NewField->DataType = ftlnteger; 
NewField->Name = Edit2->Text; 

NewField = NewTable->FieldDefs->AddFieldDef () ; // define second field 
NewField->DataType = ftString; 
NewField->Size = StrToInt (Edit3->Text) ; 
NewField->Name = Edit4->Text; 
NewTable->lndexDefs->Clear() ; 

TIndexDef *NewIndex = NewTable->lndexDefs->AddIndexDef ( ) ; // add an index 
NewIndex->Naroe = "Primarylndex"; 
NewIndex->Fields = Edit2->Text; 
NewIndex->Options « ixPriraary « ixUnique; 
// Now check for prior existence of this table 
bool Createlt = ( !NewTable->Exists) ; 
if (ICreatelt) 

if (Application->MessageBox( (AnsiString( "Overwrite table ") + Editl->Text + 

AnsiStringC?") ) .c_str() , 
"Table Exists", MB_YESN0) == IDYES) 

Createlt = true; 

if (Createlt) 
NewTable->CreateTable() ; // create the table 

Cancellazione di tabelle 

TTable e TIBTable permettono di cancellare tabelle dalla tabella di database 
sottostante senza utilizzare SQL. Per cancellare una tabella in esecuzione, chiamare il 
metodo DeleteTable del dataset. Ad esempio, la seguente istruzione elimina la tabella 
sottostante un dataset: 

CustomersTable->DeleteTable() ; 

Quando si cancella una tabella con DeleteTable, la tabella e tutti i suoi dati vanno 
definitivamente perduti. 

Se si utilizza TTable, e possibile anche cancellare le tabelle in progettazione: fare clic 
destro sul componente tabella e selezionare Delete Table dal menu di scelta rapida. 
La scelta di menu Delete Table e disponibile solo se il componente tabella 
rappresenta una tabella di database esistente (le proprieta DatabaseName e TableName 
specif icano una tabella esistente). 

Svuotamento di tabelle 



Molti dataset di tipo tabella forniscono un singolo metodo che permette di cancellare 
tutte le righe di dati nella tabella. 
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• Per TTable e per TIBTable, e possibile cancellare tutti i record chiamando in 
esecuzione il metodo EmptyTable: 

PhoneTable->EmptyTable ( ) ; 

• Per TADOTable, e possibile utilizzare il metodo DeleteRecords. 

PhoneTable->DeleteRecords (arAll) ; 

• Anche per TSQLTable e possibile utilizzare il metodo DeleteRecords. Si noti, 
tuttavia, che la versione TSQLTable di DeleteRecords non richiede mai alcun 
parametro. 

PhoneTable->DeleteRecords () ; 

• Per i dataset client, e possibile utilizzare il metodo EmptyDataSet. 

PhoneTable->EmptyDataSet ( ) ; 

Per tabelle su server SQL, questi metodi vanno a buon fine solo se si ha il privilegio 
DELETE per la tabella. 

Quando si svuota un dataset, i dati cancellati vanno definitivamente perduti. 



Sincronizzazione di tabelle 



Se si hanno due o piu dataset che rappresentano la stessa tabella di database ma non 
condividono un componente datasource, ogni dataset ha la propria vista sui dati e il 
proprio record corrente. Se si accede ai record utilizzando ognuno dei due dataset, i 
record correnti dei componenti saranno diversi. 

Se tutti i dataset sono istanze di TTable o di TIBTable o sono tutti dataset client, 
chiamando il metodo GotoCurrent e possibile forzare il record corrente di ognuno di 
questi dataset a eguagliare quello degli altri. GotoCurrent imposta il record corrente 
del proprio dataset al record corrente di un dataset corrispondente. Ad esempio, il 
seguente codice imposta il record corrente di CustomerTableOne in modo che sia lo 
stesso del record corrente di CustomerTableTwo: 

CustomerTableOne->GotoCurrent (CustomerTableTwo) ; 

ISe l'applicazione deve sincronizzare i dataset in questo modo, mettere i dataset in un 
modulo dati e includere l'header per il modulo dati in ciascuna unit che accede alle 
tabelle. Se occorre sincronizzare i dataset su schede distinte, bisogna includere il file 
header di quella scheda nella unit sorgente dell'altra scheda, e inoltre qualificare 
almeno uno dei dataset con il nome della relativa scheda. Per esempio: 

CustomerTableOne->GotoCurrent (Forra2->CustomerTableTwo) ; 

Utilizzo di dataset di tipo query 



Per utilizzare un dataset di tipo query, 

1 Collocare il componente dataset appropriato in un modulo dati o su una scheda e 
impostarne la proprieta Name a un valore univoco, consono all'applicazione. 
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2 Identificare il server di database da interrogare. Ogni dataset di tipo query compie 
l'operazione in mdo differente, ma di solito si specifica tin componente database 
connection: 

• Per TQuery, specificare un componente TDatabase o un alias BDE utilizzando la 
proprieta DatabaseName. 

• Per TADOQuery, specificare un componente TADOConnection utilizzando la 
proprieta Connection. 

• Per TSQLQuery, specificare un componente TSQLConnection utilizzando la 
proprieta SQLConnection. 

• Per TIBQuery, specificare un componente TIBConnection utilizzando la 
proprieta Database. 

Per informazioni sull'utilizzo di componenti database connection, vedere Capitolo 
21, "Connessione ai database". 

3 Specificare un'istruzione SQL nella proprieta SQL del dataset e specificare in 
modo facoltativo qualsiasi parametro da passare all'istruzione. Per ulteriori 
informazioni, vedere "Specifica della query" a pagina 22-44 e "Utilizzo dei 
parametri nelle query" a pagina 22-46. 

4 Se i dati della query devono essere utilizzati con controlli dati visuali, aggiungere 
al modulo dati un componente datasource e impostarne la proprieta DataSet al 
dataset di tipo query. II componente datasource passa il risultato della query 
(detto anche set risultato) ai componenti data-aware affinche siano visualizzati. 
Connettere i componenti data-aware al datasource utilizzando le loro proprieta 
DataSource e DataField. 

5 Attivare il componente query. Per query che restituiscono un set risultato, 
utilizzare la proprieta Active o il metodo Open. Per eseguire query che eseguono 
solo un'azione su una tabella e non restituiscono alcun set risultato, utilizza il 
metodo ExecSQL in esecuzione. Se si prevede di eseguire la query piu di una volta, 
si potrebbe volere chiamare Prepare per inizializzare lo strato di accesso ai dati e 
assemblare nella query i valori dei parametri. Per informazioni sulla preparazione 
di una query, vedere "Preparazione di query" a pagina 22-50. 

Specifica della query 



Per dataset di tipo query, utilizzare la proprieta SQL per specificare l'istruzione SQL 
che dovra eseguire il dataset.Alcuni dataset, come TADODataSet, TSQLDataSet e i 
dataset client, utilizzano una proprieta CommandText per svolgere lo stesso compito. 

La maggior parte delle query che restituiscono record sono comandi SELECT. Di 
solito, esse definiscono i campi da includere, le tabelle da cui selezionare quei campi, 
le condizioni che limitano i record da includere e l'ordine del dataset risultante. Per 
esempio: 

SELECT CustNo, OrderNo, SaleDate 

FROM Orders 

WHERE CustNo = 1225 

ORDER BY SaleDate 
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Le query che non restituiscono record includono istruzioni di tipo DDL (Data 
Definition Language) o DML(Data Manipulation Language) diverse da istruzioni 
SELECT (ad esempio, i comandi INSERT, DELETE, UPDATE, CREATE INDEX e 
ALTER TABLE non restituiscono alcun record). II linguaggio utilizzato nei comandi e 
specifico del server, ma di solito conforme alio standard SQL-92 per il linguaggio 
SQL. 

II comando SQL che si esegue deve essere conforme alle specifiche del server 
utilizzato. I dataset non sono in grado ne di valutare ne di eseguire l'istruzione SQL. 
Essi si limitano solo a passare il comando al server affinche venga eseguito. Nella 
maggior parte dei casi, il comando SQL deve essere solo un'istruzione completa SQL, 
benche l'istruzione possa essere, se necessario, anche molto complessa (ad esempio, 
un'istruzione SELECT con una clausola WHERE che utilizza numerosi operatori 
logici annidati come AND e OR). Alcuni server supportano anche una sintassi 
"batch" che permette piu istruzioni; se il server supporta tale sintassi, quando si 
specifica la query e possibile immettere piu istruzioni. 

Le istruzioni SQL utilizzate da query possono essere letterali o possono contenere 
parametri sostituibili. Query che utilizzano parametri sono chiamate query 
parametrizzate. Quando si utilizzano query parametrizzate, i valori effettivi 
assegnati ai parametri sono inseriti nella query prima di eseguire la query. L'utilizzo 
di query parametrizzate e molto flessibile, perche e possibile modificare al volo, in 
fase di esecuzione, la vista e l'accesso ai dati senza dovere modificare l'istruzione 
SQL. Per ulteriori informazioni sulle query parametrizzate, vedere "Utilizzo dei 
parametri nelle query" a pagina 22-46. 

Specifica di una query utilizzando la proprieta SQL 

Quando si utilizzando un vero dataset di tipo query (TQuery, TADOQuery, 
TSQLQuery, o TIBQuery), assegnare la query alia proprieta SQL. La proprieta SQL e 
un oggetto TStrings. Ogni singola stringa in questo oggetto TStrings e una riga 
distinta della query. L'uso di piu righe non influisce sul modo in cui la query viene 
eseguita sul server, ma la modifica e il debug della query puo risultare piu semplice 
se l'istruzione viene suddivisa in piu unita logiche: 

MyQuery->Close ( ) ; 
MyQuery->SQL->Clear() ; 

MyQuery->SQL->Add( "SELECT CustNo, OrderNO, SaleDate"); 
MyQuery->SQL->Add( "FROM Orders") ; 
MyQuery->SQL->Add ("ORDER BY SaleDate"); 
MyQuery->Open() ; 

II codice seguente mostra come modificare solo una singola riga in un'istruzione SQL 
esistente. In questo caso, la clausola ORDER BY esiste gia sulla terza riga 
dell'istruzione. E referenziata mediante la proprieta SQL utilizzando un indice pari a 
2. 

MyQuery->SQL->Strmgs [2] = "ORDER BY OrderNO"; 

Quando si specifica o si modifica la proprieta SQL, il dataset deve essere chiuso. 

In progettazione, per specificare la query utilizzare lo String List editor. Per 
visualizzare lo String List editor, fare clic nell'Object Inspector sul pulsante ellissi 
della proprieta SQL. 
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Con alcune versioni di C++Buider, se si utilizza TQuery, e possibile anche utilizzare 
SQL Builder per costruire una query in base a una rappresentazione visibile delle 
tabelle e dei campi in un database. Per utilizzare SQL Builder, selezionare il 
componente query, fare clic destro su esso per richiamare il menu di scelta rapida e 
scegliere Graphical Query Editor. Per apprendere l'utilizzo di SQL Builder, aprirlo e 
utilizzarne la Guida in linea. 

Poiche la proprieta SQL e un oggetto TStrings, e possibile caricare il testo della query 
da un file chiamando il metodo LoadFromFile di TStrings: 

MyQuery->SQL->LoadFromFile( "custquery .sql" ) ; 

Per copiare il contenuto di un oggetto string list nella proprieta SQL e possibile 
utilizzare anche il metodo Assign della proprieta SQL. Prima di copiare la nuova 
istruzione, il metodo Assign cancella automaticamente il contenuto corrente della 
proprieta SQL: 

MyQuery->SQL->Assign(Memol->Lines) ; 

Specifica di una query utilizzando la proprieta CommandText 

Quando si utilizza TADODataSet, TSQLDataSet o un dataset client, assegnare il testo 
dell'istruzione query alia proprieta CommandText: 

MyQuery->CommandText = "SELECT CustName, Address FROM Customer"; 

In fase di progettazione, e possibile immettere la query direttamente nell'Object 
Inspector o, se il dataset ha gia una connessione attiva al database, e possibile fare clic 
sul pulsante ellissi della proprieta CommandText per visualizzare il Command Text 
editor. Command Text editor elenca le tabelle disponibili e i campi in quelle tabelle, 
in modo da semplificare la composizione della query. 

Utilizzo dei parametri nelle query 



Un'istruzione SQL parametrizzata contiene parametri, o variabili, i cui valori 
possono essere modificati in progettazione o in esecuzione. I parametri possono 
sostituire valori di dati, come quelli utilizzati in una clausola WHERE per conf ronti, 
che appaiono in un'istruzione SQL. Comunemente, i parametri vengono utilizzati 
per i valori di dati passati all'istruzione. Ad esempio, nella seguente istruzione 
SELECT, i valori da inserire vengono passsati come parametri: 

INSERT INTO Country (Name, Capital, Population) 
VALUES (:Name, :Capital, : Population) 

In questa istruzione SQL, -.Name, -.Capital e Population :CustNumber sono dei 
segnaposti per i valori effettivi fornito dall'applicazione all'istruzione in fase di 
esecuzione. Notare che i nomi dei parametri iniziano con un due punti. II due punti e 
necessario per poter distinguere i nomi dei parametri dai valori letterali. E possibile 
anche includere parametri senza nome aggiungendo alia query un punto 
interrogativo (?). I parametri senza nome vengono identificati in base alia posizione, 
dal momento che non hanno nomi univoci. 

Prima che il dataset possa eseguire la query, e necessario fornire i valori a tutti i 
parametri presenti nel testo della query. TQuery, TIBQuery, TSQLQuery e i dataset 
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client utilizzano la proprieta Params per memorizzare questi valori. TADOQuery 
utilizza invece la proprieta Parameters. Params (o Parameters) e una raccolta di oggetti 
(TParam, o TParameter) in cui ogni oggetto rappresenta un singolo parametro. 
Quando si specifica il testo della query, il dataset genera questo set di oggetti 
parametro e (a seconda del tipo d dataset) inizializza tutte le rispettive proprieta che 
e in grado di desumere dalla query. 

Impostando la proprieta ParamCheck a false, e possibile sopprimere la generazione 
automatica di oggetti parametro causata dalla modifica del testo della query. Questo 
e utile per istruzioni DDL (Data Definition Language) che contengono, come parte 
dell'istruzione DDL, parametri che non sono parametri della query. Ad esempio, 
l'istruzione DDL per creare una procedura registrata potrebbe definire parametri che 
fanno parte della procedura registrata. Se si imposta ParamCheck a false, si impedisce 
a questi parametri di essere scambiati per parametri della query. 

I valori dei parametri devono essere inglobati nell'istruzione SQL prima che venga 
eseguita per la prima volta. I componenti query lo fanno automaticamente anche se 
non si chiama esplicitamente il metodo Prepare prima di eseguire la query. 

E una buona pratica di programmazione assegnare ai parametri nomi variabili, 
corrispondonti al nome effettivo della colonna a cui sono associati. Ad esempio, se un 
nome di colonna e "Number", allora il suo parametro corrispondente sarebbe 
":Number". L'uso di nomi corrispondenti e particolarmente importante se il dataset 
utilizza un datasource per ottenere i valori dei parametri da un altro dataset. Questo 
procedimento e descritto in "Impostazione di relazioni master/ detail mediante 
parametri" a pagina 22-49. 

Fornitura dei parametri in progettazione 

In progettazione, e possibile specificare i valori dei parametri utilizzando il 
Parameter collection editor. Per visualizzare il Parameter collection editor, fare clic 
nell'Object Inspector sul pulsante ellissi della proprieta Params o Parameters. Se 
l'istruzione SQL non contiene alcun parametro, nel Parameter collection editor non e 
elencato alcun oggetto. 

II Parameter collection editor e lo stesso editor di collection che viene visualizzato per 
altre proprieta di tipo collection. Dal momento che l'editor e condiviso con altre 
proprieta, il relativo menu contestuale contiene i comandi Add e Delete. Tuttavia, tali 
comandi non sono mai abilitati per i parametri delle query. L'unico modo per 
aggiungere o cancellare parametri e utilizzare l'istruzione SQL. 

Per ciascun parametro, selezionarlo nel Parameter collection editor. Quindi utilizzare 
l'Object Inspector per modificarne le proprieta. 

Quando si utilizzera la proprieta Params (oggetti TParam), si vorra esaminare o 
modificare quanto segue: 

• La proprieta DataType elenca il tipo di dati per il valore del parametro. Per alcuni 
dataset, questo valore potrebbe gia essere inizializzato correttamente. Se il dataset 
non e stato in grado di dedurre il tipo, DataType e ftUnknown ed e necessario 
modificarlo per indicare il tipo del valore del parametro. 

La proprieta DataType elenca il tipo di dati logico per il parametro. Di solito, questi 
tipi di dati si conformano ai tipi di dati del server. Per mappature specifiche dei 



I dataset 22-47 



Utilizzo di dataset di tipo query 

tipi di dati con i tipi di dati gestiti dal server, vedere la documentazione del 
meccanismo di accesso ai dati (BDE, dbExpress, InterBase). 

• La proprieta ParamType elenca il tipo del parametro selezionato. Nel caso delle 
query, la proprieta e sempre ptlnput, perche le query possono contenere solo 
parametri di input. Se il valore di PammType e ptUnknown, modificarlo in ptlnput. 

• La proprieta Value specifica un valore per il parametro selezionato. Se 
l'applicazione fornisce il valore del parametro in esecuzione, e possibile non 
compilare Value. 

Quando si utilizzera la proprieta Parameters (oggetti TParameter), si vorra esaminare o 
modificare quanto segue: 

• La proprieta DataType elenca il tipo di dati per il valore del parametro. Per alcuni 
tipi di dati, e necessario fornire ulteriori informazioni: 

• La proprieta NumericScale indica il numero di cifre decimali per i parametri 
numerici. 

• La proprieta Precision indica il numero totale di cifre per i parametri numerici. 

• La proprieta Size indica il numero di caratteri nei parametri stringa. 

• La proprieta Direction elenca il tipo del parametro selezionato. Nel caso delle 
query, la proprieta e sempre pdlnput, perche le query possono contenere solo 
parametri di input. 

• La proprieta Attributes controlla il tipo dei valori accettati dal parametro. Attributes 
puo essere impostato a una combinazione di psSigned, psNullable e psLong. 

• La proprieta Value specifica un valore per il parametro selezionato. Se 
l'applicazione fornisce il valore del parametro in esecuzione, e possibile non 
compilare Value. 

Fornitura dei parametri in esecuzione 

Per creare i parametri in esecuzione, e possibile utilizzare 

• II metodo ParamByName per assegnare i valori a un parametro in base al suo nome 
(non disponibile per TADOQuery) 

• La proprieta Paramsr.ltems o Parameters: -.Items per assegnare i valori a un 
parametro in base alia posizione ordinale del parametro nell'istruzione SQL. 

• La proprieta Paramsr.ParamValues oppure Parameters: :ParamValues per assegnare 
valori a uno o piu parametri in una linea di comando singola, in base al nome di 
ciascun parametro. 

II codice seguente utilizza ParamByName per assegnare il testo di una casella di 
modifica al parametro -.Capital: 

SQLQueryl->ParamByName( "Capital" )->AsString = Editl->Text ; 

Lo stesso codice puo essere riscritto utilizzando la proprieta Params e un indice pari a 
(si parte dall'assunto che il parametro -.Capital sia il primo parametro nell'istruzione 
SQL): 
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SQLQueryl->Params->Items [0] ->AsString = Editl->Text; 

II comando sotto riportato imposta tre parametri per volta, usando la proprieta 

Paramsr.ParamValues: 

Queryl->Params->ParamValues [ "Name ; Capital; Continent 11 ] = 
VarArrayOf (OPENARRAY (Variant , (Editl->Text , Edit2->Text, Edit3->Text) ) ) ; 

Si noti che ParamValues utilizza dei Variants, evitando la necessita di effettuare la 
conversione di tipo dei valori. 

Impostazione di relazioni master/detail mediante parametri 



Per impostare una relazione master/ detail in cui il set di dettaglio e un dataset di tipo 
query, e necessario specificare una query che utilizza parametri. Questi parametri 
fanno riferimento ai valori del campo corrente del dataset master. Perche i valori del 
campo corrente del dataset master cambiano dinamicamente in fase di esecuzione, e 
necessario collegare di nuovo i parametri del set di dettaglio ogni volta che cambia il 
record principale. Benche sia possibile scrivere del codice per compiere l'operazione 
utilizzando un gestore di evento, tutti i dataset di tipo query tranne TIBQuery 
forniscono un meccanismo piu semplice grazie all'utilizzo della proprieta DataSource. 

Se i valori dei parametri di una query parametrizzata non vengono collegati in fase di 
progettazione o specificati in esecuzione, i dataset di tipo query tentano di fornire un 
valore ai parametri in base alia proprieta DataSource. DataSource identifica un dataset 
differente che viene esaminato alia ricerca di nomi di campo che corrispondano ai 
nomi dei parametri non collegati. Questo dataset di ricerca puo essere un qualsiasi 
tipo di dataset. Prima di creare il dataset di dettaglio che lo utilizza, e necessario 
creare e riempire il dataset di ricerca. Se nel dataset di ricerca vengono trovate le 
corrispondenze, il dataset di dettaglio collega i valori dei parametri ai valori dei 
campi nel record corrente a cui punta la sorgente dati. 

Per illustrare il funzionamento, si prendano in esame due tabelle: una tabella di 
clienti e una tabella di ordini. Per ogni cliente, la tabella degli ordini contiene una 
serie di ordini fatti dal cliente. La tabella Customer include un campo ID che specifica 
un codice cliente univoco. La tabella degli ordini include un campo CustID che 
specifica l'ID del cliente che ha fatto un ordine. 

II primo passo consiste nel configurare il dataset Customer: 

1 Aggiungere all'applicazione un dataset di tipo tabella e collegarlo alia tabella 
Customer. 

2 Aggiungere un componente TDataSource di nome CustomerSource. Impostarne la 
proprieta DataSet al dataset aggiunto al punto 1. Questo datasource ora 
rappresenta il dataset Customer. 

3 Aggiungere un dataset di tipo query e impostarne la proprieta SQL a 

SELECT CustID, OrderNo, SaleDate 

FROM Orders 

WHERE CustID = :ID 
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Si noti che il nome del parametro e identico al nome del campo nella tabella master 
(Customer). 

4 Impostare la proprieta DataSource del dataset di dettaglio a Customer Source. 
L'impostazione di questa proprieta rende il dataset di dettaglio una query 
collegata. 

In esecuzione, al parametro :ID dell'istruzione SQL per il dataset di dettaglio non 
viene assegnato un valore, e pertanto il dataset cerca fra le colonne del dataset 
identificato da CustomersSource una corrispondenza del parametro in base al nome. 
Customer sSource ricava i propri dati dal dataset master, il quale, a sua volta, ricava i 
propri dati dalla tabella Customer. Poiche la tabella Customer contiene una colonna 
di nome "ID", il valore del campo ID nel record corrente del dataset master viene 
assegnato al parametro :ID dell'istruzione SQL del dataset di dettaglio. I dataset sono 
collegati tramite una relazione master-detail. Ogni volta che nel dataset Customers il 
record corrente cambia, viene eseguita l'istruzione SELECT del dataset di dettaglio 
per ricercare tutti gli ordini in base all'identificativo del cliente corrente. 

Preparazione di query 



La preparazione di una query e un passo facoltativo che precede l'esecuzione della 
query. La preparazione di una query sottomette l'istruzione SQL e gli eventuali 
parametri alio strato di accesso ai dati e al server di database per l'analisi sintattica e 
per l'allocazione e l'ottimizzazione delle risorse. Con alcuni dataset, in fase di 
preparazione della query, il dataset puo eseguire delle ulterori operazioni di 
configurazione. Queste operazioni migliorano le prestazioni della query, rendendo 
piu rapida l'applicazione, specialmente quando funzionano con query aggiornabili. 

Un'applicazione puo preparare una query impostando la proprieta Prepared a true. 
Se non si prepara una query prima di eseguirla, il dataset la prepara 
automaticamente ogni volta che si chiamano i metodi Open o ExecSQL. Sebbene il 
dataset prepari le query automaticamente, e possibile migliorare le prestazioni 
preparando esplicitamente il dataset prima di aprirlo per la prima volta. 

CustQuery->Prepared = true; 

Quando si prepara esplicitamente il dataset, le risorse allocate per l'esecuzione 
dell'istruzione non vengono liberate finche non si imposta Prepared a false. 

Impostare la proprieta Prepared a false se si desidera essere certi che il dataset venga 
preparato di nuovo prima di essere eseguito (ad esempio, nel caso si aggiunga un 
parametro). 

Quando si modifica il testo della proprieta SQL di una query, il dataset si chiude 
automaticamente e annulla la preparazione della query. 

Esecuzione di query che non restituiscono un set risultato 



Quando una query restituisce un set di record (come una query SELECT), la si esegue 
esattamente come se si stesse riempiendo un qualsiasi dataset con dei record: si 
imposta Active a true o si chiama il metodo Open. 
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Comunque, spesso i comandi SQL non restituiscono alcun record. Tali comandi 
includono istruzioni di tipo DDL (Data Definition Language) o DML (Data 
Manipulation Language) diverse da istruzioni SELECT (ad esempio, i comandi 
INSERT, DELETE, UPDATE, CREATE INDEX e ALTER TABLE non restituiscono 
alcun record). 

Per tutti i dataset di tipo query, e possibile eseguire una query che non restituisce un 
set risultato chiamando ExecSQL: 

CustomerQuery->ExecSQL() ; // Does not return a result set 

Se la query viene eseguita piu volte, e conveniente impostare la proprieta Prepared a 
true. 

Benche la query non restituisca alcun record, si potrebbe voler conoscere il numero di 
record coinvolti nell'operazione (ad esempio, il numero di record cancellati da una 
query DELETE). La proprieta Rows Affected restituisce il numero di record coinvolti, 
dopo una chiamata a ExecSQL. 

Quando in fase di progettazione non si sa se la query restituira o meno un set 
risultato (ad esempio, se l'utente fornisce la query dinamicamente in fase di 
esecuzione), e possibile codificare entrambi i tipi di istruzioni di esecuzione della 
query in un blocco try...catch. Mettere una chiamata al metodo Open nella clausola 
try. Una query di azione viene eseguita quando si attiva la query con il metodo Open, 
ma in aggiunta si verifica un'eccezione. Controllare l'eccezione e ignorarla nel caso si 
limiti ad indicare la mancanza di un set risultato (ad esempio, TQuery indica un tale 
evento con un'eccezione di tipo ENoResultSet). 

Utilizzo di set risultato unidirezionali 



Se un dataset di tipo query restituisce un set risultato, riceve anche un cursor o un 
puntatore al primo record in quel set risultato. II record puntato dal cursor e il record 
attualmente attivo.il record corrente e quello i cui valori dei campi sono visualizzati 
in componenti data-aware associati al datasource del set risultato. A meno che non si 
stia utilizzando db Express, per impostazione predefinita, questo cursor e 
bidirezionale. Un cursor bidirezionale puo spostarsi tra i suoi record sia in avanti che 
a ritroso. II supporto di un cursor bidirezionale ha un peso gestionale aggiuntivo e 
puo rallentare alcune query. 

Se non e necessario essere in grado di spostarsi nel set risultato in entrambe le 
direzione, TQuery e TIBQuery permettono di migliorare le prestazioni della query 
richiedendo invece un cursor unidirezionale. Per richiedere un cursor unidirezionale, 
impostare la proprieta UniDirectional a true. 

Impostare UniDirectional prima di preparare ed eseguire la query. II seguente codice 
mostra l'impostazione di UniDirectional prima di preparare ed eseguire una query: 

if ( !CustomerQuery->Prepared) 

{ 

CustomerQuery->UniDirectional = true; 
CustomerQuery->Prepared = true; 

} 

CustomerQuery->Open() ; // Returns a result set with a one-way cursor 
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Non confondere la proprieta UniDirectional con un dataset unidirezionale. I dataset 
unidirezionali (TSQLDataSet, TSQLTable, TSQLQuery e TSQLStoredProc) utilizzano 
dbExpress, che restituisce solo cursor unidirezionali. Oltre a limitare la capacita di 
spostamento a ritroso, i dataset unidirezionali non bufferizzano i record e pertanto 
hanno limitazioni aggiuntive (come l'incapacita di utilizzare i filtri). 

Utilizzo di dataset di tipo procedura registrata 



II modo in cui l'applicazione utilizza una procedura registrata dipende da come e 
stata codificata la procedura registrata, dal fatto che restituisca o meno dati e in che 
modo, dallo specif ico server di database utilizzato, o da una combinazione di tutti 
questi fattori. 

In generale, per accedere a una procedura registrata su un server, un'applicazione 
deve: 

1 Collocare il componente dataset appropriato in un modulo dati o su una scheda e 
impostarne la proprieta Name a un valore univoco, consono all'applicazione. 

2 Identificare il server di database che definisce la procedura registrata. Ogni dataset 
di tipo procedura registrata lo fa in modo diverso, ma di solito si specifica un 
componente database connection: 

• Per TStoredProc, specificare un componente TDatabase o un alias BDE 
utilizzando la proprieta DatabaseName. 

• Per TADOStoredProc, specificare un componente TADOConnection utilizzando 
la proprieta Connection. 

• Per TSQLStoredProc, specificare un componente TSQLConnection utilizzando la 
proprieta SQLConnection. 

• Per TIBStoredProc, specificare un componente TIBConnection utilizzando la 
proprieta Database. 

Per informazioni sull'utilizzo di componenti database connection, vedere Capitolo 
21, "Connessione ai database". 

3 Specificare la procedura registrata da eseguire. Per la maggior parte dei dataset di 
tipo procedura registrata, lo si fa impostando la proprieta StoredProcName. 
Un'eccezione e TADOStoredProc, che ha invece una proprieta ProcedureName. 

4 Se la procedura registrata restituisce un cursor da usare con controlli dati visuali, 
aggiungere al modulo dati un componente datasource e impostarne la proprieta 
DataSet al dataset di tipo procedura registrata. Connettere i componenti data- 
aware al datasource utilizzando le loro proprieta DataSource e DataField. 

5 Fornire, se necessario, i valori dei parametri di input per la procedura registrata. 
Se il server non fornisce informazioni su tutti i parametri della procedura 
registrata, potrebbe essere necessario specificare ulteriori informazioni per i 
parametri di input, come i nomi dei parametri e i tipi di dati. Per i dettagli sui 
parametri delle procedure registrate, consultare "Operazioni con i parametri delle 
procedure registrate" a pagina 22-53. 
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6 Eseguire la procedura registrata. Per procedure registrate che restituiscono un 
cursor, utilizzare la proprieta Active o il metodo Open. Per eseguire procedure 
registrate che non restituisce alcun risultato o che restituiscono solo parametri di 
output, utilizzare il metodo ExecProc in fase di esecuzione. Se si prevede di 
eseguire la procedura registrata piu di una volta, potrebbe essere oportuno 
chiamare Prepare per inizializzare lo strato di accesso ai dati e inglobare i valori dei 
parametri nella procedura registrata. Per informazioni sulla preparazione di una 
query, vedere "Esecuzione di procedure registrate che non restituiscono un set 
risultato" a pagina 22-56. 

7 Elaborare gli eventuali risultati. Questi risultati possono essere restituiti come 
parametri risultato e parametri di output, oppure possono essere restituiti come 
set risultato che riempie il dataset di tipo procedura registrata. Alcune procedure 
registrate restituiscono piu cursor. Per dettagli su come accedere ai cursor 
aggiuntivi, vedere "Prelievo di piu set risultato" a pagina 22-57. 

Operazioni con i parametri delle procedure registrate 



Esistono quattro tipi di parametri che e possibile associare a procedure registrate: 

• Parametri di input, utilizzati per passare valori a una procedura registrata per 
l'elaborazione. 

• Parametri di output, utilizzati da una procedura registrata per passare a 
un'applicazione i valori restituiti. 

• Parametri di input/output, utilizzati per passare valori a una procedura registrata 
per l'elaborazione e utilizzati dalla procedura registrata per passare 
all'applicazione i valori restituiti. 

• Un parametro risultato, utilizzato da alcune procedure registrate per restituire a 
un'applicazione un valore di errore o di stato. Una procedura registrata pud 
restituire un solo parametro risultato. 

II fatto che una procedura registrata utilizzi un particolare tipo di parametro dipende 
sia dall'implementazione generale del linguaggio delle procedure registrate sul 
server di database sia dalla specifica istanza della procedura registrata. Per tutti i 
server, le singole procedure registrate possono utilizzare o meno parametri di input. 
D'altra parte, alcuni utilizzi dei parametri sono tipici del server. Ad esempio, su MS- 
SQL Server e Sybase, le procedure registrate restituiscono sempre un parametro 
risultato, mentre l'implementazione InterBase di una procedura registrata non 
restituisce mai un parametro risultato. 

L'accesso ai parametri di una procedura registrata e garantito dalla proprieta Params 
(in TStoredProc, TSQLStoredProc, TIBStoredProc) o dalla proprieta Parameters (in 
TADOStoredProc). Quando si assegna un valore alia proprieta StoredProcName (o 
ProcedureName), il dataset genera automaticamente oggetti per ogni parametro della 
procedura registrata. Per alcuni dataset, se il nome della procedura registrata non 
vinespecificato fino al mometo dell'esecuzione, gli oggetti per ogni parametro 
devono essere creati da programma in quel preciso momento. La mancata specifica 
della procedura registrata e la creazione manualmente gli oggetti TParam o 
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TParameter permette di utilizzare un singolo dataset con tutte le procedure registrate 
disponibili. 

Oltre ai parametri di output e risultato, alcune procedure registrate restituiscono un 
dataset. Le applicazioni possono visualizzare i record del dataset in controlli data- 
aware, ma devono elaborare separatamente i parametri di output e risultato. 

Impostazione dei parametri in progettazione 

E possibile specificare in fase progettazione i valori dei parametri della procedura 
registrata utilizzando il Parameter collection editor. Per visualizzare il Parameter 
collection editor, fare clic nell'Object Inspector sul pulsante ellissi della proprieta 

Parentis o Parameters. 

E possibile assegnare valori ai parametri di input selezionandoli nel Parameter 
collection editor e utilizzando l'Object Inspector per impostarne la proprieta Value. 
Tuttavia, non si devono modificare i nomi o i tipi di dati dei parametri di input 
segnalati dal server. In caso contrario, quando si eseguira la procedura registrata 
verra sollevata un'eccezione. 

Alcuni server non riportano i nomi dei parametri o i tipi di dati. In questi casi, e 
necessario configurare i parametri utilizzando manualmente l'editor Parameter 
collection. Per aggiungere parametri, fare clic destro e scegliere il comando Add. Per 
ogni parametro aggiunto, e necessario fame una descrizione completa. Anche se non 
e necessario aggiungere alcun parametro, si dovrebbero controllare le proprieta dei 
singoli oggetti parametro per assicurasi che siano corretti. 

Se il dataset ha una proprieta Params (oggetti TParam), e necessario specificare 
correttamente le seguenti proprieta: 

• La proprieta Name indica il nome del parametro cosi come definito dalla 
procedura registrata. 

• La proprieta DataType riporta il tipo di dati per il valore del parametro. Quando si 
utilizza TSQLStoredProc, alcuni tipi di dati richiedono ulteriori informazioni: 

• La proprieta NumericScale indica il numero di cifre decimali per i parametri 
numerici. 

• La proprieta Precision indica il numero totale di cifre per i parametri numerici. 

• La proprieta Size indica il numero di caratteri nei parametri stringa. 

• La proprieta ParamType riporta il tipo del parametro selezionato. Puo essere 
ptlnput (per parametri di input), ptOutput (per parametri di output), ptlnputOutput 
(per parametri di input/output) o ptResult (per parametri risultato). 

• La proprieta Value specifica un valore per il parametro selezionato. Non e mai 
possibile impostare i valori per i parametri di output e risultato. Questi tipi di 
parametri hanno valori che vengono impostati dall'esecuzione della procedura 
registrata. Nel caso dei parametri di input/ output, se l'applicazione rornisce i 
valori dei parametri in esecuzione, e possibile non compilare Value. 

Se il dataset utilizza una proprieta Parameters (oggetti TParameter), e necessario 
specificare correttamente le seguenti proprieta: 
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• La proprieta Name indica il nome del parametro cosi come definito dalla 
procedura registrata. 

• La proprieta DataType riporta il tipo di dati per il valore del parametro. Per alcuni 
tipi di dati, e necessario fornire ulteriori informazioni: 

• La proprieta NumericScale indica il numero di cifre decimali per i parametri 
numerici. 

• La proprieta Precision indica il numero totale di cifre per i parametri numerici. 

• La proprieta Size il numero di caratteri nei parametri stringa. 

• La proprieta Direction riporta il tipo del parametro selezionato. Puo essere pdlnput 
(per parametri di input), pdOutput (per parametri di output), pdlnputOutput (per 
parametri di input/output) o pdReturnValue (per parametri risultato). 

• La proprieta Attributes controlla il tipo dei valori accettati dal parametro. Attributes 
puo essere impostato a una combinazione di psSigned, psNullable e psLong. 

• La proprieta Value specifica un valore per il parametro selezionato. Non impostare 
i valori per i parametri di output e risultato. Nel caso dei parametri di input/ 
output, se l'applicazione fornisce i valori dei parametri in esecuzione, e possibile 
non compilare Value. 

Utilizzo di parametri in esecuzione 

Con alcuni dataset, se il nome della procedura registrata non viene specificato fino al 
momento dell'esecuzione, per i parametri non verra creato automaticamente alcun 
oggetto TParam ed dovranno essere creati da programma. E possibile fare do 
istanziando un nuovo oggetto TParam oppure il metodo TParamsr.AddParam: 

TParam *Pl, *P2; 

StoredProcl->StoredProcNarae = "GET_EMP_PROJ" ; 

StoredProcl->Params->Clear() ; 

PI = new TParam(StoredProcl->Params, pt Input); 

P2 = new TParam(StoredProcl->Params, pt Output); 

try 

{ 

StoredProcl->Params->Items [0] ->Name = "EMPJSO"; 
StoredProcl->Params->ltems [1] ->Name = "PR0J_ID"; 
StoredProcl->ParamByName("EMP_NO")->AsSmallInt = 52; 
StoredProcl->ExecProc ( ) ; 

Editl->Text = StoredProcl->ParamByName("PROJ_ID" ) ->AsString; 

} 

finally 

{ 

delete PI; 
delete P2; 

} 

Anche se non e necessario aggiungere in fase di esecuzione i singoli oggetti 
parametro, potrebbe essere necessario accedere ai singoli oggetti parametro per 
assegnare dei valori ai parametri di input e ottenere dei valori dai parametri di 
output. E possibile utilizzare il metodo ParamByName del dataset per accedere ai 
singoli parametri in base al loro nome. Ad esempio, il codice seguente imposta il 
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valore di un parametro di input/output, esegue la procedura registrata e recupera il 
valore restituito: 

SQLDataSetl->ParamByName("IN_OUTVAR n )->AsInteger = 103; 
SQLDataSetl->ExecSQL() ; 

int Result = SQLDataSetl->ParamByName( "IN_0UTVAR" ) ->AsInteger; 

Preparazione delle procedure registrate 



Come con i dataset di tipo query, i dataset di tipo procedura registrata devono essere 
preparati prima che possano eseguire la procedura registrata. La preparazione di una 
procedura registrata dice alio strato di accesso ai dati e al server di database di 
allocare le risorse per la procedura registrata e di inglobare i parametri. Queste 
operazioni possono migliorare prestazioni. 

Se si tenta di eseguire una procedura registrata prima averla prepararla, sara 
preparata automaticamente dal dataset, il quale, dopo l'esecuzione, prowedera ad 
annullarne la preparazione. Se si prevede di eseguire una procedura registrata piu 
volte, risulta molto piu efficiente prepararla esplicitamente impostando la proprieta 
Prepared a true. 

MyProc->Prepared = true; 

Quando si prepara esplicitamente il dataset, le risorse allocate per l'esecuzione 
dell'istruzione non vengono liberate finche non si imposta Prepared a false. 

Impostare la proprieta Prepared a false se si desidera essere certi che il dataset venga 
preparato di nuovo prima dell'esecuzione (ad esempio, nel caso si cambiano i 
parametri utilizzando le procedure in overload di Oracle). 

Esecuzione di procedure registrate che non restituiscono un set 
risultato 



Quando una procedura registrata restituisce un cursor, la si esegue esattamente come 
se si stesse riempiendo un qualsiasi dataset con dei record: si imposta Active a true o 
si chiama il metodo Open. 

Tuttavia, spesso le procedure registrate non restituiscono nessun dato, o 
restituiscono solo dei risultati nei parametri di output. E possibile eseguire una 
procedura registrata che non restituisce un set risultato chiamando ExecProc. Dopo 
avere eseguito la procedura registrata, e possibile utilizzare il metodo ParamByName 
per leggere il valore del parametro risultato o di un qualsiasi parametro di output: 

MyStoredProcedure->ExecProc() ; // Does not return a result set 
Editl->Text = MyStoredProcedure->ParamByName("OUTVAR") ->AsString; 

TADOStoredProc non ha un metodo ParamByName. Per ottenere i valori dei parametri 
di output quando di utilizza ADO, accedere agli oggetti parametro utilizzando la 
proprieta Parameters. 

Se la procedure viene eseguita piu volte, e conveniente impostare la proprieta 
Prepared a true. 
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Prelievo di piu set risultato 



Alcune procedure registrate restituiscono piu set di record.Appena lo si apre, il 
dataset recupera solo il primo set. Se si utilizzano TSQLStoredProc oppure 
TADOStoredProc, e possibile accedere agli altri set di record chiamando il metodo 

NextRecordSet o NextRecordset: 

TCustomSQLDataSet *DataSet2 = SQLStoredProcl->NextRecordSet ( ) ; 

Con TSQLStoredProc, il metodo NextRecordSet restituisce un nuovo componente 
TCustomSQLDataSet che fornisce l'accesso al successivo set di record. In 
TADOStoredProc, NextRecordset restituisce un'interfaccia che puo essere assegnata 
alia proprieta RecordSet di un dataset ADO esistente. Per entrambe le classi, il metodo 
restituisce il numero di record nel dataset restituito come parametro di output. 

La prima volta che si chiama NextRecordSet, il metodo restituisce il secondo set di 
record. La successiva chiamata a NextRecordSet restituisce nuovamente un terzo 
dataset e cosi via, finche non vi sono piu altri set di record. Quando non vi sono piu 
altri cursor, NextRecordSet restituisce NULL. 
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Capitolo 




Operazioni con i componenti campo 



Questo capitolo descrive le proprieta, gli eventi e i metodi comuni all'oggetto TField e 
ai suoi discendenti. I componenti campo rappresentano singoli campi (colonne) nei 
dataset. Questo capitolo descrive, inoltre, come usare i componenti campo per 
controllare la visualizzazione e la modifica dei dati nelle applicazioni. 

I componenti campo sono sempre associati a un dataset. Non si utilizza mai un 
oggetto TField direttamente nelle applicazioni. Invece, ogni componente campo 
nell'applicazione e un discendente di TField, specifico per il tipo di dati di una 
colonna in un dataset. I componenti campo forniscono controlli data-aware, come 
TDBEdit e TDBGrid, per accedere ai dati in una particolare colonna del dataset 
associate 

Generalmente parlando, un singolo componente campo rappresenta le caratteristiche 
di una singola colonna, o campo di un dataset, come ad esempio il tipo di dato e la 
dimensione. Rappresenta anche le caratteristiche di visualizzazione dei campi, quali 
l'allineamento, il formato di visualizzazione e di modifica. Un componente 
TFloatField, ad esempio, ha quattro proprieta che influenzano direttamente l'aspetto 
dei suoi dati: 

Tabella 23.1 Proprieta di TFloatField che influenzano la visualizzazione dei dati 
Proprieta Funzione 

Alignment Specifica se i dati sono visualizzati con allineamento a sinistra, a destra o al 

centre 

DisplayWidth Specifica il numero di cifre da visualizzare contemporaneamente in un controllo. 

DisplayFormat Specifica il formato di visualizzazione dei dati (ad esempio, quante cifre decimali 
mostrare). 

EditFormat Specifica come visualizzare un valore in fase di modifica. 



Man mano che si passa da un record a un altro all'interno del dataset, un componente 
campo permette di visualizzare e modificare il valore di quel campo nel record 
corrente. 
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I vari componenti campo hanno sia molte proprieta in comune (ad esempio 
DisplayWidth e Alignment), sia proprieta specifiche in base al relativo tipo di dati (ad 
esempio Precision per TFloatField). Ciascuna di queste proprieta influenza il modo in 
cui appaiono i dati in una scheda agli utenti di un'applicazione. Alcune proprieta, 
come Precision, possono anche influire sul valore che l'utente puo immettere in un 
controllo durante la modifica o l'inserimento dei dati. 

Tutti i componenti campo di un dataset sono dinamici (generati automaticamente in 
base alia struttura associata delle tabelle del database), o persistenti (generati in base 
ai nomi di campo e proprieta specif ici impostati nel Fields editor). I campi dinamici e 
persistenti hanno potenza differente e sono adatti a tipi differenti di applicazioni. Le 
sezioni seguenti descrivono in maggior dettaglio i campi dinamici e persistenti e 
suggeriscono come scegliere fra l'uno e l'altro tipo. 

Componenti campo dinamici 



I componenti campo vengono generati dinamicamente per impostazione predefinita. 
Infatti, la prima volta che si pone un qualsiasi dataset in un modulo dati, si deve 
specificare in che modo quel dataset preleva i dati e aprirlo. Un componente campo e 
dinamico se viene creato automaticamente in base alle caratteristiche fisiche 
intrinseche dei dati rappresentati da un dataset. I dataset generano un componente 
campo per ciascuna colonna nei dati associati. L'esatto discendente TField creato per 
ciascuna colonna, viene determinato in base alle informazioni sul tipo di campo 
ricevute dal database o (per TClientDataSet) da un componente provider. 

I campi dinamici sono temporanei. Essi esistono finche un dataset e aperto. Ogni 
volta che si riapre un dataset che usa campi dinamici, il dataset rigenera una serie 
completamente nuova di componenti campo dinamici in base alia struttura attiva dei 
dati del database associate al dataset. Se le colonne nei dati associati vengono 
modificate, la volta successiva in cui viene aperto un dataset che usa i componenti 
campo dinamici, anche i componenti campo generati automaticamente vengono 
modificati in conseguenza. 

L'utilizzo dei campi dinamici e consigliato in applicazioni che richiedono flessibilita 
in fase di visualizzazione e di modifica dei dati. Ad esempio, per creare uno 
strumento di esplorazione del database come SQL explorer, si devono usare campi 
dinamici perche ogni tabella di database ha numero e tipi di colonne differenti. E 
bene usare i campi dinamici anche in applicazioni in cui l'interazione dell'utente con 
i dati si verifica soprattutto all'interno di componenti griglia e, come e noto, i dataset 
usati dall'applicazione subiscono frequenti modifiche. 

Per usare campi dinamici in un'applicazione: 

1 Posizionare i dataset e le sorgenti dati in un modulo dati. 

2 Associare i dataset ai dati. Questo implica l'utilizzo di un componente connection 
o di un provider per collegarsi alia sorgente dati e l'impostazione di tutte le 
proprieta che specificano quali sono i dati che il dataset rappresenta. 

3 Associare le sorgenti dati al dataset. 
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4 Collocare i controlli data-aware nelle schede dell'applicazione, aggiungere 
l'header del modulo dati nella unit di ciascuna scheda e associare ciascun controllo 
data-aware a un datasource nel modulo. Inoltre, associare un campo a ciascun 
controllo data-aware che lo richiede. Si noti che poiche si stanno utilizzando 
componenti campo dinamici, non c'e alcuna garanzia che il nome di campo che si 
specifica esistera al momento dell'apertura del dataset. 

5 Aprire il dataset. 

Indipendentemente dalla semplicita d'uso, i campi dinamici possono imporre delle 
limitazioni. Senza scrivere codice, non e possibile modificare le impostazioni 
predefinite di visualizzazione e modifica dei campi dinamici, non si puo modificare, 
senza rischi, la sequenza con cui vengono visualizzati i campi dinamici e non si puo 
impedire l'accesso ai campi del dataset. Non si possono creare campi aggiuntivi per il 
dataset, quali ad esempio campi calcolati o campi di consultazione, e non si puo 
ridefinire il tipo di dato predefinito di un campo dinamico. Per aumentare il controllo 
e la flessibilita sui campi nelle applicazioni database, occorre richiamare Fields editor 
per creare componenti campo persistenti per il dataset. 

Componenti campo persistenti 



Per impostazione predefinita, i campi del dataset sono dinamici. Le loro proprieta e 
la disponibilita sono impostate automaticamente e non possono essere modificate in 
alcun modo. Per controllare appieno le proprieta e gli eventi di un campo, si devono 
creare per il dataset campi persistenti. I campi persistenti, consentono di: 

• Impostare o modificare la visibilita del campo o le caratteristiche in fase di 
progetto o in esecuzione. 

• Creare nuovi campi, come campi di consultazione, campi calcolati e campi 
aggregati, che basano il proprio valore sui campi esistenti di un dataset. 

• Eseguire la convalida dei dati immessi. 

• Eliminare componenti campo dall'elenco dei componenti persistenti, per impedire 
all'applicazione di accedere a determinate colonne di un database associato. 

• Definire nuovi campi solitamente per sostituire i campi esistenti, basati sulle 
colonne della tabella o della query associata al dataset. 

In fase di progetto, e opportuno utilizzare Fields Editor per creare liste di componenti 
campo persistenti utilizzati dai dataset nell'applicazione. Le liste di campi persistenti 
sono registrate nell'applicazione e non cambiano anche in caso di variazione della 
struttura del database associato al dataset. Dopo aver creato i campi persistenti con 
Fields editor, e possibile creare anche i relativi gestori di evento che rispondono alle 
modifiche dei valori dei dati e convalidano i dati immessi. 

Quando si creano campi persistenti per un dataset, in fase di progetto e in esecuzione 
sono disponibili per l'applicazione solo i campi selezionati. In fase di progetto, e 
sempre possibile utilizzare il Fields editor per aggiungere o rimuovere i campi 
persistenti di un dataset. 
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Tutti i campi usati da un singolo dataset sono o persistenti o dinamici. Non si 
possono mischiare questi due tipi di campo in un singolo dataset. Se per un dataset si 
creano campi persistenti e successivamente si vuole tornare ai campi dinamici, 
occorre rimuovere dal dataset tutti i campi persistenti. Per maggiori informazioni sui 
campi dinamici, consultare "Componenti campo dinamici" a pagina 23-2. 

Una delle ragioni principali per usare i campi persistenti consiste nel fatto che essi 
consentono di controllare completamente l'aspetto e la visualizzazione dei dati. E 
anche possibile controllare l'aspetto delle colonne nelle griglie associate ai dati. Per 
informazioni su come controllare l'aspetto delle colonne nelle griglie 
consultare"Creazione di una griglia personalizzata" a pagina 19-18. 

Creazione di campi persistenti 



I componenti campo persistenti creati con Fields editor consentono di accedere ai dati 
associati tramite programma, in modo efficiente, leggibile e con salvaguardia del 
tipo. L'uso dei componenti campo persistenti, garantisce che ogni volta che si esegue 
un'applicazione, essa usa e visualizza sempre le stesse colonne, nello stesso ordine, 
anche se la struttura fisica del database associato e stata modificata.I componenti 
associati ai dati e il programma, che si aspettano di operare su determinati campi, 
funzionano sempre come previsto. Se si cancella o si modifica una colonna su cui e 
basato un componente campo persistente, C++Builder genera un'eccezione anziche 
eseguire l'applicazione e scontrarsi con una colonna inesistente o con dati che non 
coincidono con quelli previsti. 

Per creare campi persistenti per un dataset: 

1 Inserire un dataset in un modulo dati. 

2 Collegare il dataset ai dati sottostanti. Di solito questo implica l'associazione del 
dataset a un componente connection o a un provider e la specifica di tutte le 
proprieta atte a descrivere i dati. Ad esempio, se si utilizza TADODataSet, e 
possibile impostare la proprieta Connection a un componente TADOConnection 
correttamente configurato e impostare la proprieta CommandText a una query 
valida. 

3 Fare doppio clic sul componente dataset nel modulo dati per richiamare Fields 
editor. Questo possiede una barra di titolo, dei pulsanti di spostamento e una 
casella di riepilogo. 

La barra del titolo di Fields editor presenta sia il nome del modulo dati, o della 
scheda contenente il dataset, sia il nome del dataset stesso. Ad esempio, se viene 
aperto il dataset Customers nel modulo dati CustomerData, la barra del titolo 
visualizza la scritta 'CustomerData->Customers' o la parte di essa che puo essere 
contenuta nella barra del titolo. 

Sotto la barra del titolo e presente una serie di pulsanti di navigazione che 
consentono, durante il progetto, di effettuare lo scorrimento, record per record, in 
un dataset attivo o di saltare al primo o all'ultimo record. Se il dataset non e attivo 
oppure e vuoto, i pulsanti di navigazione sono disattivati. Se il dataset e 
unidirezionale, i pulsanti per il passaggio all'ultimo record e al record precedente 
sono sempre inattivi. 
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La casella di riepilogo visualizza i nomi dei componenti campo persistenti per il 
dataset. Alia prima apertura di Fields editor per un nuovo dataset, l'elenco e vuoto 
perche i componenti campo del dataset sono dinamici e non persistenti. Se Fields 
editor viene richiamato per un dataset che possiede gia componenti campo 
persistenti, i nomi dei campi saranno riportati nella casella di riepilogo. 

4 Scegliere Add Fields dal menu contestuale del Fields editor. 

5 Selezionare i campi da rendere persistenti nella finestra di dialogo Add Fields. Per 
impostazione predefinita, quando si apre la finestra di dialogo vengono 
selezionati tutti i campi. Tutti i campi selezionati dall'utente diventano campi 
persistenti. 

La finestra di dialogo Add Fields verra chiusa e i campi selezionati appariranno nella 
casella di riepilogo di Fields Editor. I campi riportati nella casella di riepilogo di 
Fields Editor sono persistenti. Se il dataset e attivo, i pulsanti di navigazione Next e 
(se il dataset non e unidirezionale) Last sopra la casella di riepilogo, sono abilitati. 

Da questo momento in poi, a ogni apertura del dataset, non creera piu componenti 
campo dinamici per ogni colonna del database sottostante. Creera invece solo 
componenti persistenti per i campi specificati. 

Ad ogni apertura del dataset, verifica che ciascun campo persistente non calcolato 
esista o possa essere creato dai dati del database. Se cio non e possibile, il dataset 
solleva un'eccezione avvertendo che il campo non e valido e il dataset non viene 
aperto. 

Disposizione dei campi persistenti 



L'ordine con cui sono elencati i componenti campo persistenti nella casella di 
riepilogo di Fields Editor e l'ordine predefinito con cui i campi appariranno in un 
componente griglia associato ai dati. L'ordine dei campi pud essere modificato 
trascinando i campi nella casella di riepilogo. 

Per cambiare la posizione di un campo: 

1 Selezionare i campi. E possibile selezionare uno o piu campi alia volta. 

2 Trascinare i campi in una nuova posizione. 

Se si seleziona una serie non contigua di campi e li si trascina in una nuova posizione, 
vengono inseriti come un blocco contiguo. Nell'ambito del blocco, l'ordine dei campi 
non viene modificato. 

In alternativa, si puo selezionare il campo e usare Ctrl+Su e Ctrl+Giu per modificare 
l'ordine di un singolo campo dell'elenco. 

Definizione di nuovi campi persistenti 



Oltre a trasformare i campi esistenti del dataset in campi persistenti, e possibile creare 
anche campi persistente speciali in aggiunta o in sostituzione di altri campi 
persistenti di un dataset. 
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Nuovi campi persistenti servono solo ai fini della visualizzazione. I dati contenuti in 
esecuzione non vengono conservati, o perche esistono gia altrove nel database o 
perche sono prowisori. La struttura fisica dei dati associati al dataset non viene 
modificata in alcun modo. 

Per creare un nuovo componente campo persistente, occorre chiamare il menu 
contestuale di Fields editor e scegliere New Field. Appare cosi la finestra di dialogo 
New Field. 

La finestra di dialogo New Fields contiene tre caselle di gruppo: Field properties, 
Field type e Lookup definition. 

• La casella di gruppo Field properties permette di immettere informazioni generali 
sui componenti campo. Immettere il nome del campo nella casella di testo Name. II 
nome immesso corrisponde alia proprieta FieldName del componente campo. La 
finestra di dialogo New Field utilizza questo nome per costruire un nome di 
componente nella casella di testo Component. II nome visualizzato nella casella di 
testo Component corrisponde alia proprieta Name del componente campo ed e 
fornito solo a fini informativi (Name e l'identificativo utilizzato nel codice sorgente 
per fare riferimento al componente campo). La finestra di dialogo elimina 
qualsiasi cosa immessa direttamente nella casella di testo Component. 

• La casella combinata Type del gruppo Field properties permette di specificare il 
tipo di dati del componente campo. E necessario indicare un tipo di dati per 
qualsiasi nuovo componente campo create Per esempio, per visualizzare valori di 
valuta in virgola mobile in un campo, selezionare Currency nell'elenco a discesa. 
Utilizzare la casella di testo Size per specificare il numero massimo di caratteri che 
possono essere visualizzati o immessi in un campo basato su stringhe, oppure la 
dimensione dei campi Bytes e VarBytes. Per tutti gli altri tipi di dati, Size e privo di 
significato. 

• II gruppo di pulsanti di opzione Field consente di specificare il tipo del nuovo 
componente campo da creare. II tipo predefinito e Data. Se si sceglie Lookup, 
vengono attivate le caselle di testo Dataset e Source Fields nella casella del gruppo 
della definizione Lookup. E anche possibile creare campi di tipo Calculated e, se si 
sta lavorando con un dataset client, si possono creare campi di tipo InternalCalc o 
Aggregate. La tabella seguente descrive i tipi di campi che si possono creare: 

Tabella 23.2 Tipi di campi persistenti particolari 
Tipo di 

campo Funzione 



Data Sostituisce un campo esistente (ad esempio per modificarne il tipo di dato) 

Calculated Visualizza i valori calcolati in esecuzione dal gestore di evento OnCalcFields di un 
dataset. 

Lookup Recupera valori da un determinato dataset in fase di esecuzione in base al criterio 

di ricerca specificato dall'utente. (Non supportato dai dataset unidirezionali) 

InternalCalc Visualizza i valori calcolati in esecuzione da un dataset client e memorizzati coi 
suoi dati. 

Aggregate Visualizza un valore di sintesi dei dati di un gruppo di record. 
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La casella di gruppo di definizione Lookup viene utilizzata solo per creare campi di 
ricerca. Per maggiori informazioni, consultare "Definizione di un campo di 
consultazione" a pagina 23-9. 

Definizione di un campo dati 

Un campo dati sostituisce un campo esistente in un dataset. Per esempio, per motivi 
di programmazione pud essere necessario sostituire un TSmalllntField con un 
TIntegerField. Poiche il tipo di dati di un campo non puo essere modificato 
direttamente, e necessario definire un nuovo campo per sostituirlo. 

Anche se e un nuovo campo, il campo definito per sostituire un campo esistente deve 
derivare i valori dei propri dati da una colonna esistente in una tabella associata a un 
dataset. 

Per creare un campo dati di sostituzione per un campo di una tabella sottostante un 
dataset: 

1 Rimuovere il campo dall'elenco dei campi persistenti assegnati per il dataset, 
quindi scegliere New Field dal menu contestuale. 

2 Nella finestra di dialogo New Field immettere nella casella di testo Name il nome 
di un campo esistente nella tabella del database. Non immettere un nuovo nome di 
campo. In questo modo, si specifica il nome del campo dal quale il nuovo campo 
derivera i dati. 

3 Scegliere un nuovo tipo di dati per il campo dalla casella combinata Type. II tipo di 
dati scelto deve essere diverso da quello del campo che si sta sostituendo. Non e 
possibile sostituire un campo stringa di una determinata dimensione con un 
campo stringa di dimensione diversa. Si deve tenere presente che, anche se il tipo 
di dati sara diverso, deve pur sempre essere compatible con il tipo di dati del 
campo nella tabella sottostante. 

4 All'occorrenza, immettere le dimensioni del campo nella casella di modifica Size. 
Size vale solo per i campi di tipo TStringField, TBytesField e TVarBytesField. 

5 Selezionare Data nel gruppo Field type, se gia non e selezionato. 

6 Scegliere OK. La finestra di dialogo New Field verra chiusa, il campo dati appena 
definito sostituira il campo esistente specificato al punto 1 e la dichiarazione dei 
componenti nel modulo dati o nell'header della scheda sara aggiornata. 

Per modificare le proprieta o gli eventi associati a un componente campo, selezionare 
il nome del componente nella casella di riepilogo di Fields Editor, quindi modificare 
le relative proprieta o i relativi eventi con l'Object Inspector. Per ulteriori 
informazioni sulla modifica delle proprieta e degli eventi dei componenti campo, 
vedere "Impostazione di proprieta ed eventi dei campi persistenti" a pagina 23-11. 

Definizione di un campo calcolato 

Un campo calcolato visualizza i valori calcolati in esecuzione dal gestore di evento 
OnCalcFields di un dataset. Per esempio, e possibile creare un campo stringa che 
visualizza i valori concatenati di altri campi. 

Per creare un campo calcolato nella finestra di dialogo New Field: 
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1 Nella casella di modifica Name, immettere un nome per il campo calcolato. Non 
immettere il nome di un campo esistente. 

2 Nella casella combinata Type, scegliere un tipo di dati per il campo. 

3 All'occorrenza, immettere le dimensioni del campo nella casella di modifica Size. 
Size vale solo per i campi di tipo TStringField, TBytesField e TVarBytesField. 

4 Selezionare l'opzione Calculated o InternalCalc nel gruppo Field type. 
InternalCalc e disponibile solo se si opera con un dataset client. La differenza 
significativa fra questi tipi di campi calcolati e che i valori calcolati per un campo 
InternalCalc sono memorizzati e recuperati come parte dei dati del dataset client. 

5 Scegliere OK. II campo calcolato appena definito verra automaticamente aggiunto 
alia fine dell'elenco dei campi persistenti nella casella di riepilogo di Fields Editor e 
la dichiarazione del componente verra aggiunta automaticamente all 'header della 
sheda o del modulo dati. 

6 Inserire il codice che calcola i valori per il campo nel gestore di evento OnCalcFields 
del dataset. Per ulteriori informazioni sulla scrittura del codice per calcolare i 
valori dei campi, vedere "Programmazione di un campo calcolato" a pagina 23-8. 

Per modificare le proprieta o gli eventi associati a un componente campo, selezionare 
il nome del componente nella casella di riepilogo di Fields Editor, quindi modificare 
le relative proprieta o i relativi eventi con l'Object Inspector. Per ulteriori 
informazioni sulla modifica delle proprieta e degli eventi dei componenti campo, 
vedere "Impostazione di proprieta ed eventi dei campi persistenti" a pagina 23-11. 

Programmazione di un campo calcolato 

Dopo aver definito un campo calcolato, e necessario scrivere il codice per calcolarne il 
valore. Altrimenti, il campo avra sempre un valore nullo. II codice per un campo 
calcolato viene inserito nell'evento OnCalcFields del relativo dataset. 

Per programmare un valore per un campo calcolato: 

1 Selezionare il componente dataset nell'elenco a discesa dell'Object Inspector. 

2 Scegliere la pagina Object Inspector Events. 

3 Fare doppio clic sulla proprieta OnCalcFields per richiamare o creare una 
procedura CalcFields per il componente dataset. 

4 Scrivere il codice che imposta i valori e le altre proprieta del campo calcolato. 

Per esempio, si supponga di aver creato un campo calcolato CityStateZip per la 
tabella Customers nel modulo dati CustomerData. CityStateZip dovrebbe visualizzare 
la citta, lo stato e il codice di avviamento postale di un'azienda su una singola riga di 
un controllo associato ai dati. 

Per aggiungere del codice alia procedura CalcFields per la tabella Customers, 
selezionare la tabella Customers dall'elenco a discesa dell'Object Inspector, accedere 
alia pagina Events e fare doppio clic sulla proprieta OnCalcFields. 

La procedura TCustomerData::CustomersCalcFields appare nella finestra del codice 
sorgente della unit. Aggiungere il seguente codice alia procedura per calcolare il 
campo: 
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CustomersCityStateZip->Value = CustomersCity->Value + AnsiString ( " , *) + 
CustomersState->Value + AnsiString!" ") + CustoraersZip->Value; 

Quando si scrive il gestore di evento OnCalcFields per un campo calcolato 
internamente, e possibile migliorare le prestazioni controllando la proprieta State del 
dataset client e ricalcolando il valore solo quando State e dsInternalCalc. Per ulteriori 
informazioni consultare il paragrafo "Uso di campi calcolati internamente nei dataset 
client" a pagina 27-11. 

Definizione di un campo di consultazione 

Un campo di consultazione e un campo a sola lettura che, durante l'esecuzione, 
visualizza i valori in base ai criteri di ricerca specificati dall'utente. Nella sua forma 
piu semplice, al campo di consultazione viene passato il nome di un campo esistente 
in cui eseguire la ricerca, un valore di campo da cercare e un campo diverso, in un 
dataset di consultazione, di cui dovrebbe visualizzare il valore. 

Per esempio, si consideri un'applicazione per la gestione della vendita per 
corrispondenza che consenta a un operatore di utilizzare un campo di consultazione 
per determinare automaticamente la citta e lo stato corrispondenti a un codice di 
avviamento postale indicate) da un cliente. La colonna in cui eseguire la ricerca 
potrebbe essere denominata ZipTable->Zip, il valore da cercare e il codice di 
avviamento postale del cliente in Order->CustZip e i valori da restituire sarebbero 
quelli per le colonne ZipTable->City e ZipTable-> State per il record in cui ZipTable->Zip 
corrisponde al valore attivo nel campo Order->CustZip. 

I dataset unidirezionali non supportano i campi di consultazione. 

Per creare un campo di consultazione nella finestra di dialogo New Field: 

1 Nella casella di testo Name, immettere un nome per il campo di consultazione. 
Non immettere il nome di un campo esistente. 

2 Nella casella combinata Type, scegliere un tipo di dati per il campo. 

3 All'occorrenza, immettere le dimensioni del campo nella casella di modifica Size. 
Size vale solo per i campi di tipo TStringField, TBytesField e TVarBytesField. 

4 Selezionare Lookup nel gruppo Field type. Selezionando Lookup, vengono 
abilitate le caselle combinate Dataset e Key Fields. 

5 Scegliere nell'elenco a discesa della casella combinata Dataset il dataset in cui 
cercare i valori di campi. II dataset di consultazione deve essere diverso dal dataset 
del componente campo, altrimenti in fase di esecuzione verra sollevata 
un'eccezione dovuta a un riferimento circolare. Specificando un dataset di 
consultazione, le caselle combinate Lookup Keys e Result Field vengono abilitate. 

6 Scegliere nell'elenco a discesa Key Fields un campo del dataset corrente per cui 
devono essere trovati dei valori corrispondenti. Per trovare corrispondenze per 
piu di un campo, invece di scegliere i nomi dei campi dall'elenco a discesa, 
immetterli direttamente. Separare piu nomi di campo con punti e virgola. Se si usa 
piu di un campo, usare componenti campo persistenti. 

7 Scegliere nell'elenco a discesa Lookup Keys un campo del dataset di consultazione 
da confrontare con il campo Source Fields specificato al punto 6. Se si specifica piu 
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di un campo chiave, specificare lo stesso numero di chiavi di ricerca. Per 
specificare piu di un campo, immettere direttamente i nomi dei campi, separandoli 
con dei punti e virgola. 

8 Scegliere nell'elenco a discesa Result Field un campo del dataset di consultazione 
da restituire come valore del campo di consultazione che si sta creando. 

Quando si progetta e si esegue un'applicazione, i valori del campo di consultazione 
vengono determinati prima di calcolare i valori dei campi calcolati. E possibile basare 
i campi calcolati sui campi di consultazione, ma non viceversa. 

E possibile utilizzare la proprieta LookupCache per affinare il modo in cui vengono 
stabiliti i campi di consultazione. LookupCache determina se i valori di un campo di 
consultazione devono essere caricati in memoria appena si apre il dataset, o se 
devono essere consultati dinamicamente ogni volta che il record attivo del dataset 
viene modificato. LookupCache determina se i valori di un campo di consultazione 
devono essere caricati in memoria appena si apre il dataset, o se devono essere 
consultati dinamicamente ogni volta che il record attivo del dataset viene modificato. 
Conviene impostare LookupCache a true per mettere in cache i valori di un campo di 
consultazione quando e improbabile che il LookupDataSet venga modificato e il 
numero dei singoli valori di consultazione e piccolo. Mettere in cache i valori di 
consultazione puo incrementare le prestazioni, perche i valori di consultazione di 
ogni serie di valori LookupKey Fields vengono precaricati appena si apre il DataSet. 
Quando si modifica il record attivo del DataSet, invece di accedere a LookupDataSet, 
l'oggetto campo puo localizzare il suo Value nella cache. Questo incremento di 
prestazioni e pariicolarmente significativo se il LookupDataSet si trova su una rete che 
ha un accesso lento. 

E possibile usare una cache di ricerca per fornire i valori tramite programma anziche 

| tramite un dataset secondario. Assicurarsi che la proprieta LookupDataSet sia NULL. 

Quindi, utilizzare il metodo Add della proprieta LookupList per riempirlo con i valori 
di consultazione. Impostare la proprieta LookupCache a true. II campo usera l'elenco 
di ricerca fornito senza sovrascriverlo con i valori di un dataset di ricerca. 

Se i KeyFields di ogni record di DataSet hanno valori diversi, il carico di lavoro 
derivante dal cercare i valori nella cache puo essere maggiore di qualsiasi beneficio in 
prestazioni fornito dalla cache. II carico di lavoro derivante dal cercare i valori nella 
cache aumenta col numero di valori distinti che possono essere richiesti da KeyFields. 

Se LookupDataSet e volatile, mettere in cache valori di consultazione puo condurre a 
risultati imprecisi. Per aggiornare i valori nella cache di consultazione occorre 
chiamare RefreshLookupList . RefreshLookupList rigenera la proprieta LookupList che 
contiene il valore del LookupResultField per ogni serie di valori di LookupKey Fields. 

Quando in l'esecuzione si imposta LookupCache, per inizializzare la cache occorre 
chiamare RefreshLookupList. 

Definizione di un campo di aggregazione 

Un campo di aggregazione visualizza valori da un' aggregazione di mantenimento in 
un dataset cliente. Un'aggregazione e un calcolo che riepiloga i dati di un gruppo di 
record. Per informazioni piu dettagliate sulle aggregazioni di manutenzione, 
consultare "Uso delle aggregazioni di manutenzione" a pagina 27-12. 
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Per creare un campo di aggregazione nella finestra di dialogo NewField: 

1 Immettere un nome per il campo nella casella di modifica Name. Non immettere il 
nome di un campo esistente. 

2 Scegliere il tipo di dati di aggregazione per il campo dalla casella combinata Type. 

3 Selezionare Aggregate nel gruppo di pulsanti di opzioni per Field type. 

4 Scegliere OK. II campo di aggregazione appena definito viene aggiunto 
automaticamente al dataset client, e la sua proprieta Aggregates viene poi 
aggiornata per includere la specifica di aggregazione appropriata. 

5 Inserire l'operazione di calcolo prevista per l'aggregazione nella proprieta 
ExprText del campo di aggregazione appena create Per ulteriori informazioni 
sulla definizione di un campo di aggregazione, consultare il paragrafo "Specifica 
delle aggregazioni" a pagina 27-12. 

Una volta creato un TAggregateField persistente, e possibile collegare un controllo 
TDBText al campo di aggregazione. II controllo TDBText visualizzera poi il valore del 
campo di aggregazione che e pertinente al record corrente del dataset client 
sottostante. 



Cancellazione di componenti campo persistenti 



La cancellazione di un componente campo persistente e utile per accedere a un 
sottoinsieme di colonne disponibili in una tabella e per definire un proprio campo 
persistente per sostituire una colonna di una tabella. Per rimuovere uno o piu 
componenti di campo persistenti di un dataset occorre: 

1 Selezionare il campo o i campi da rimuovere nella casella di riepilogo Fields 
editor. 

2 Premere Cane. 

I campi selezionati possono essere cancellati anche chiamando il menu contestuale e 
scegliendo Delete. 

I campi rimossi non sono piu disponibili per il dataset e non possono essere 
visualizzati da controlli associati ai dati. E sempre possibile ricreare un componente 
campo persistente cancellato per errore, ma qualsiasi modifica apportata in 
precedenza alle proprieta o agli eventi si perde. Per maggiori informazioni, 
consultare "Creazione di campi persistenti" a pagina 23-4. 

Se si rimuovono tutti i componenti campo persistenti per un dataset, questo torna a 
usare i componenti campo dinamici per ogni colonna della tabella sottostante del 
database. 



Impostazione di proprieta ed eventi dei campi persistenti 



In fase di progetto e possibile impostare proprieta e personalizzare eventi per i 
componenti campo persistenti. Le proprieta controllano il modo in cui un campo 
viene visualizzato da un componente associato ai dati, determinando per esempio se 
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puo apparire in TDBGrid o se il suo valore puo essere modificato. Gli eventi 
controllano quello che accade quando i dati di un campo vengono recuperati, 
modificati, impostati o convalidati. 

Per impostare le proprieta di un componente campo o per scrivere gestori di evento 
personalizzati per esso, selezionare il componente nel Fields editor o nell'elenco dei 
componenti dell'Object Inspector. 

Impostazione delle proprieta di visualizzazione e di modifica in progettazione 

Per modificare le proprieta di visualizzazione di un componente campo selezionato, 
passare sulla pagina Properties della finestra dll'Object Inspector. La seguente tabella 
riepiloga le proprieta di visualizzazione che e possibile modificare. 



Tabella 23.3 Proprieta dei 
Proprieta 

Alignment 



componenti campo 
Funzlone 



Allinea a sinistra, allinea a destra o centra il contenuto di un campo in un 
componente associato ai dati. 

ConstraintErrorMessage Specifica il testo da visualizzare quando le modifiche contrastano con una 
condizione di vincolo. 



CustomConstraint 
Currency 

DisplayFormat 

DisplayLabel 

DisplayWidth 

EditFormat 

EditMask 

FieldKind 
FieldName 

HasConstraints 
ImportedConstraint 

Index 

LookupDataSet 
LookupKeyFields 
LookupResultField 
MaxValue 



Specifica un vincolo locale da applicare ai dati durante la modifica. 

Solo campi numerici. true: visualizza valori monetari. 

false (impostazione predefinita): non visualizza valori monetari. 

Specifica il formato dei dati visualizzati in un componente associato ai 
dati. 

Specifica il nome di colonna di un campo in un componente griglia 
associato ai dati. 

Specifica la larghezza, in caratteri, di una colonna di griglia che visualizza 
questo campo. 

Specifica il formato di modifica dei dati in un componente associato ai 
dati. 

In un campo modificabile, limita l'immissione di dati ai soli tipi e 
intervalli di caratteri specificati e indica i caratteri speciali non 
modificabili che appaiono nel campo (trattini, parentesi e cosi via). 

Specifica il tipo di campo da creare. 

Specifica il nome effettivo di una colonna di tabella da cui il campo trae il 
proprio valore e tipo di dati. 

Indica se ci sono condizioni di vincolo imposte su un campo. 

Specifica un vincolo SQL importato dal Data Dictionary o da un server 
SQL. 

Specifica l'ordine dei campi in un dataset. 

Specifica la tabella usata per consultare i valori del campo quando Lookup 
e impostato a true. 

Specifica il campo o i campi del dataset di consultazione che devono 
corrispondere quando si effettua una consultazione. 

Specifica il campo del dataset di consultazione da cui copiare i valori da 
inserire in questo campo. 

Solo campi numerici. Specifica il valore massimo che un utente puo 
immettere nel campo. 
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Tabella 23.3 
Proprieta 

MinValue 

Name 
Origin 
Precision 
Readonly 



Size 
Tag 

Transliterate 
Visible 



Proprieta dei componenti campo 
Funzione 



Solo campi numerici. Specifica il valore minimo che un utente pud 
immettere nel campo. 

Specifica il nome del componente campo in C++Builder. 

Specifica il nome del campo come appare nel database associato. 

Solo campi numerici. Specifica il numero di cifre significative. 

true: visualizza i valori dei campi nei controlli data-aware, ma ne 
impedisce la modifica. 

false (impostazione predefinita): consente la visualizzazione e la modifica 
dei valori dei campi. 

Specifica il numero massimo di caratteri che possono essere visualizzati o 
immessi in un campo di tipo stringa, oppure la dimensione in byte dei 
campi TBytesField e TVarBytesField. 

Zona di memoria per interi lunghi, a disposizione dei programmatori in 
ogni componente per l'utilizzo secondo le esigenze. 

true (impostazione predefinita): specifica che la traduzione da e verso le 
rispettive impostazioni locali si verifichera mentre i dati vengono 
trasferiti dal dataset al database. 

false: La traduzione relativa alle impostazioni locali non si verifica. 

true (impostazione predefinita): consente la visualizzazione di un campo 
in una griglia data-aware. 

false: Impedisce la visualizzazione di un campo in un componente griglia 
associato ai dati. 

I componenti definiti dall'utente possono prendere decisioni relative alia 
visualizzazione in base a questa proprieta. 



Non tutte le proprieta sono disponibili per tutti i componenti campo. Per esempio, un 
componente campo di tipo TStringField non possiede proprieta Currency, MaxValue o 
DisplayFormat, mentre un componente di tipo TFloatField non possiede la proprieta 

Size. 

Anche se lo scopo della maggior parte delle proprieta e semplice, alcune proprieta, 
quali Calculated, richiedono ulteriori operazioni di programmazione perche siano 
veramente utili. Altre, quali DisplayFormat, EditFormat e EditMask, sono correlate; le 
loro impostazioni devono essere coordinate. Per ulteriori informazioni sull'uso di 
DisplayFormat, EditFormat ed EditMask, vedere "Controllo e mascheratura dell'input" 
a pagina 23-15. 

Impostazione delle proprieta del componente campo in esecuzione 

In fase di esecuzione e possibile usare e gestire le proprieta del componente campo. 
Accedere ai componenti campo persistenti in base al nome, dove il nome puo essere 
ottenuto concatenando il nome del campo al nome del dataset. 

II codice che segue, ad esempio, imposta a true la proprieta ReadOnly per il campo 
CityStateZip nella tabella Customer. 

CustomersCityStateZip->ReadOnly = true; 

E questa istruzione modifica l'ordine dei campi impostando a 3 la proprieta Index del 
campo CityStateZip nella tabella Customer: 
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CustomersCityStateZip->Index = 3; 

Creazione di set di attributi per i componenti campo 

Quando vari campi dei dataset utilizzati dall'applicazione condividono le stesse 
proprieta di formattazione (quali Alignment, DisplayWidth, DisplayFormat, EditFormat, 
MaxValue, MinValue, e cosi via), e piu pratico impostare le proprieta per un solo 
campo e memorizzare quindi queste proprieta come set di attributi nel Data 
Dictionary. I set di attributi memorizzati nel dizionario dati possono essere 
facilmente applicati ad altri campi. 

Set di attributi e Data Dictionary sono solo disponibili per i dataset BDE. 
Per creare un set di attributi basato su un componente campo in un dataset: 

1 Fare doppio clic sul dataset per richiamare il Fields editor. 

2 Selezionare il campo per cui impostare le proprieta. 

3 Impostare le proprieta desiderate per il campo nell'Object Inspector. 

4 Fare clic con il pulsante destro del mouse sulla casella di riepilogo di Fields Editor 
per aprire il menu contestuale. 

5 Scegliere Save Attributes per salvare le impostazioni delle proprieta del campo 
attivo come set di attributi nel Data Dictionary. 

II nome predefinito del set di attributi e quello del campo attivo. Se dal menu 
contestuale si sceglie Save Attributes As, invece di Save Attributes, e possibile 
specificare per il set di attributi un nome diverso. 

Una volta che si e creato un nuovo set di attributi e lo si e aggiunto al Data Dictionary, 
e possibile poi associarlo ad altri componenti campo persistenti. Anche se in seguito 
si rimuovera l'associazione, il set di attributi resta definite nel Data Dictionary. 

E inoltre possibile creare set di attributi direttamente da SQL Explorer. Quando si 
crea un set di attributi utilizzando SQL Explorer, tale set viene aggiunto al Data 
Dictionary, ma non viene applicato a nessun campo. SQL Explorer consente di 
specificare altri due attributi: un tipo di campo (TFloatField, TStringField, e cosi via) e 
un controllo data-aware (come TDBEdit, TDBCheckBox, e cosi via) che vengono 
automaticamente collocati su una scheda non appena si trascina sulla scheda un 
campo basato sull'attributo impostato. Per ulteriori informazioni, vedere la guida in 
linea relativa a SQL Explorer. 

Associazione di set di attributi ai componenti campo 

Quando vari campi dei dataset utilizzati dall'applicazione condividono le stesse 
proprieta di formattazione (quali Alignment, DisplayWidth, DisplayFormat, EditFormat, 
MaxValue, MinValue, e cosi via), e queste impostazioni di proprieta sono state salvate 
come set di attributi nel Data Dictionary, questi set di attributi possono essere 
facilmente applicati ai campi, senza dover ricreare manualmente le impostazioni per 
ciascun campo. Inoltre, se in seguito vengono modificate nel Data Dictionary le 
impostazioni degli attributi, le modifiche verranno applicate automaticamente a tutti 
i campi associati al set non appena verranno aggiunti al dataset nuovi componenti 
campo. 
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Per applicare un set di attributi a un componente campo 

1 Fare doppio clic sul dataset per richiamare il Fields editor. 

2 Selezionare il campo cui applicare un set di attributi. 

3 Chiamare il menu contestuale e scegliere Associate attributes. 

4 Nella finestra di dialogo Attribute set name, selezionare o immettere Associate 
attributes da applicare. Se nel Data Dictionary c'e un set di attributi che ha lo 
stesso nome del campo attivo, il nome di quel set di attributi apparira nella casella 
di testo. 

Se in una f ase successiva si modifica un set di attributi presente nel Data Dictionary, e 
necessario applicare nuovamente il set di attributi a ciascun componente campo che 
ne fa uso. Quando si riapplicano gli attributi e possibile richiamare il Fields editor e 
selezionare piu componenti campo all'interno di un dataset. 

Rimozione delle associazioni degli attributi 

Se si cambia idea sull'associazione di un set di attributi a un campo, e possibile 
rimuovere l'associazione seguendo questi passi: 

1 Chiamare il Fields editor per il dataset che contiene il campo. 

2 Selezionare il campo o i campi da cui rimuovere l'associazione dell'attributo. 

3 Chiamare il menu contestuale di Fields editor e scegliere Unassociate Attributes. 

Annullando l'associazione di un attributo impostato non si modifica alcuna proprieta 
del campo. II campo conserva le impostazioni che aveva quando gli e stato applicato 
il set di attributi. Per modificare queste proprieta, selezionare il campo in Fields 
editor e impostarne le proprieta con l'Object Inspector. 

Controllo e mascheratura dell'input 

La proprieta EditMask consente di controllare il tipo e l'intervallo dei valori che un 
utente puo immettere in un componente data-aware associato a componenti 
TStringField, TDateField, TTimeField, TDateTimeField, e TSQLTimeStampField. E 
possibile usare maschere esistenti o crearne di proprie. II modo piu semplice per 
utilizzare e creare maschere di inserimento dati e usare Input Mask editor. E 
possibile, comunque, immettere le maschere direttamente nel campo EditMask 
nell'Object Inspector. 

Per componenti TStringField, la proprieta EditMask rappresenta anche il formato di 
visualizzazione. 

Per richiamare l'lnput Mask editor per un componente campo: 

1 Selezionare il componente in Fields Editor o nell'Object Inspector. 

2 Fare clic sulla pagina Properties nell'Object Inspector. 

3 Fare doppio clic sulla colonna dei valori del campo EditMask nell'Object Inspector, 
oppure fare clic sul pulsante con i puntini di sospensione. Verra richiamato Input 
Mask editor. 
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La casella di testo Input Mask consente di creare e modificare un formato di 
maschera. La griglia Sample Masks consente di selezionare una maschera 
predefinita. Se si seleziona una maschera di esempio, il relativo formato appare nella 
casella di testo Input Mask, in cui e possibile modificarlo o utilizzarlo senza 
variazioni. Nella casella di testo Test Input e possibile collaudare le immissioni 
consentite all'utente per le maschere. 

II pulsante Masks consente di caricare nella griglia Sample Masks un set di maschere 
personalizzate - se ne sono state create - in modo da semplificare la selezione. 

Uso dei formati predefiniti per i campi numerici, data e ora 

C++Builder possiede routine incorporate per i formati di visualizzazione e modifica e 
una formattazione predefinita intelligente per i componenti TFloatField, 
TCurrencyField, TIntegerField, TSmalllntField, TWordField, TDateField, TdateTimeField 
e TTimeField. Per utilizzare queste routine, non occorre fare nulla. 

La formattazione predefinita viene eseguita dalle seguenti routine: 



Tabella 23.4 Routine di formattazione dei componenti campo 




FormatFloat TFloatField, TCurrencyField 

FormatDateFime TDateField, FTimeField, TDateTimeField, 

SQLTimeStampToString TSQLTimeStampField 

FormatCurr TCurrencyField, FBCDField 

BcdFoStrF TFMTBCDField 



Per un determinate componente campo sono disponibili solo le proprieta di formato 
appropriate al proprio tipo di dati. 

Le convenzioni di formattazione predefinita per i valori di data, ora, valuta e per i 
valori numerici si basano sulle proprieta Impostazioni internazionali del Pannello di 
controllo. Ad esempio, utilizzando le impostazioni predefinite per gli Stati Uniti, una 
colonna FFloatField con la proprieta Currency impostata a true imposta la proprieta 
DisplayFormat per il valore 1234.56 a $1234.56, mentre EditFormat e 1234.56. 

In fase di progetto o durante l'esecuzione, e possibile modificare le proprieta 
DisplayFormat e EditFormat di un componente campo per ridefinire le impostazioni di 
visualizzazione predefinite per quel campo. Si possono scrivere anche i gestori di 
evento OnGetFext e OnSetFext per compiere una formattazione personalizzata dei 
componenti campo in fase di esecuzione. 

Gestione degli eventi 

Come molti componenti, i componenti campo hanno eventi associati. E possibile 
assegnare metodi che svolgano il compito di gestori di questi eventi. Grazie alia 
scrittura di questi eventi, e possibile reagire al verificarsi di questi eventi che 
riguardano l'immissione dei dati nei campi tramite controlli associati ai dati e 
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compiere operazioni specifiche. La seguente tabella elenca gli eventi associati ai 
componenti campo: 



Tabella 23.5 Eventi dei componenti campo 




OnChange Chiamato quando il valore di un campo cambia. 

OnGetText Chiamato quando si recupera il valore di un componente campo per 

visualizzarlo o modificarlo. 



OnSetText Chiamato quando si imposta il valore di un componente campo. 

OnValidate Chiamato per convalidare il valore di un componente campo ogni volta che 

viene modificato in seguito a un'operazione di modifica o di inserimento. 



Gli eventi OnGetText e OnSetText sono utili principalmente per i programmatori che 
desiderano eseguire formattazioni personalizzate che esulano dalle funzioni di 
formattazione incorporate. OnChange e utile per eseguire operazioni specifiche 
dell'applicazione associate alia modifica dei dati, quali l'abilitazione o la 
disabilitazione di menu o di controlli visuali. OnValidate e utile per controllare 
nell'applicazione la convalida dei dati immessi prima di restituire i valori a un server 
di database. 

Per scrivere un gestore di evento per un componente campo: 

1 Selezionare il componente. 

2 Selezionare nell'Object Inspector la pagina Events. 

3 Fare doppio clic sul campo Value relativo al gestore di evento, per visualizzarne la 
finestra del codice sorgente. 

4 Creare o modificare il codice del gestore. 
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I metodi dei componenti campo disponibili in esecuzione consentono di convertire i 
valori del campo da un tipo di dati a un altro e di impostare il fuoco sul primo 
controllo associato ai dati in una scheda associata con un componente di campo. 

II controllo del fuoco nei componenti associati ai dati collegati a un campo e 
importante quando un'applicazione esegue la convalida dei dati a livello di record in 
un gestore di evento di un dataset (come BeforePost). La convalida puo essere eseguita 
sui campi di un record indipendentemente dal fatto che il fuoco si trovi sul relativo 
controllo associato ai dati. Nel caso la convalida fallisca per uno specif ico campo del 
record, si puo ottenere che il fuoco si sposti sul controllo associato ai dati che contiene 
dati non corretti, in modo che l'utente possa immettere le correzioni. 

II fuoco dei componenti associati ai dati di un campo si controlla col metodo 
FocusControl del campo. FocusControl imposta il fuoco sul primo controllo associato ai 
dati in una scheda associata a un campo. Prima di convalidare il campo, un gestore di 
evento dovrebbe chiamare il metodo FocusControl del campo. II codice che segue 
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illustra come chiamare il metodo FocusControl per il campo Company nella tabella 

Customer:: 

CustomersCompany->FocusControl () ; 

La tabella che segue elenca gli altri metodi del componente campo e il loro uso. Per 
un elenco completo e per informazioni particolareggiate sull'uso di ciascun metodo, 
consultare le voci relative a TFidd e ai suoi discendenti nella guida in linea VCL 

Reference. 

Tabella 23.6 Altri metodi dei componenti campo 
Metodo Funzione 

Assign Value Imposta un valore di campo a un determinate valore usando una funzione di 

conversione automatica basata sul tipo del campo. 

Clear Svuota il campo e ne imposta il valore a NULL. 

GetData Recupera dal campo i dati non formattati. 

Is ValidChar Determina se un carattere immesso da un utente in un controllo associato ai 

dati per impostare un valore e un carattere consentito. 

SetData Assegna al campo i dati non formattati. 



Visualizzazione, conversione e accesso ai valori di campo 



I controlli associati ai dati quali TDBEdit e TDBGrid visualizzano automaticamente i 
valori associati ai componenti campo. Se la modifica e consentita per il dataset e per i 
controlli, i controlli associati ai dati possono anche inviare valori nuovi e modificati al 
database. In generale, le proprieta e i metodi incorporati nei controlli associati ai dati 
consentono a questi ultimi di connettersi ai dataset, visualizzare i valori ed effettuare 
aggiornamenti senza richiedere ulteriori operazioni di programmazione. E 
consigliabile ricorrere ad essi ogni qualvolta sia possibile nelle applicazioni database. 
Per ulteriori informazioni sui controlli data-aware, consultare il Capitolo 19, "Uso dei 
controlli dati". 

I controlli standard possono anche visualizzare e modificare valori di database 
associati ai componenti campo. Tuttavia, con i controlli standard potrebbe essere 
necessario scrivere del codice aggiuntivo. Ad esempio, quando si utilizzano controlli 
standard, e compito dell'applicazione rilevare quando e il momento di aggiornare i 
controlli perche i valori del campo sono stati modificato. Se il dataset ha un 
componente datasource, e possibile utilizzarne gli eventi per assolvere questo 
compito. In particolare, l'evento OnDataChange consente di sapere quando puo essere 
necessario aggiornare il valore di un controllo e l'evento OnStateChange puo essere 
d'aiuto nel determinare quando attivare o disattivare i controlli. Per ulteriori 
informazioni su questi eventi, consultare "Risposta alle modifiche mediate dal 
datasource" a pagina 19-4. 

I seguenti paragrafi spiegano come operare con i valori dei campi in modo che sia 
possibile visualizzarli nei controlli standard. 



23-18 Guida alia programmazione 



Visualizzazione dei valori dei componenti campo nei controlli 
standard 



Un'applicazione puo accedere ai valori delle colonne di un datset mediante la 
proprieta Value di un componente campo. Ad esempio, il seguente gestore di evento 
OnDataChange aggiorna il testo in un controllo TEdit poiche il valore del campo 
Customer 'sComp 'any potrebbe essere stato cambiato: 

void __fastcall TForml: :TablelDataChange (TObject *Sender, TField *Field) 
{ 

Edit3->Text = CustomersCompany->Value; 

} 

Questo metodo funziona bene per i valori stringa, ma puo richiedere ulteriore 
programmazione per gestire le conversioni per altri tipi di dati. Fortunatamente, i 
componenti campo possiedono funzioni native per gestire le conversioni. 

Per accedere ai valori dei campi e modificarli, e possibile anche ricorrere ai Variant. 
Per ulteriori informazioni sull'uso dei variant per accedere ai valori dei campi e 
impostarli, vedere "Accesso ai valori dei campi con la proprieta predefinita del 
dataset" a pagina 23-21. 

Conversione dei valori di campo 



Le proprieta di conversione cercano di convertire un tipo di dati in un altro. Per 
esempio, la proprieta AsString converte i valori numerici e booleani sotto forma di 
stringhe. La seguente tabella elenca le proprieta di conversione dei componenti 
campo e indica quali proprieta sono consigliate per ciascuna classe di componente 
campo:: 





AsVariant 


AsString 


Aslnteger 


AsFloat 

AsCurrency 

AsBCD 


AsDateTime 
AsSQLTimeStamp 


AsBoolean 


TStringField 


Si 


ND 


Si 


Si 


Si 


Si 


TWideStringField 


Si 


Si 


Si 


Si 


Si 


Si 


TIntegerField 


Si 


Si 


ND 


Si 






TSmalllntField 


Si 


Si 


Si 


Si 






TWordField 


Si 


Si 


Si 


Si 






TLargeintField 


Si 


Si 


SiSi 


Si 






TFloatField 


Si 


Si 


Si 


Si 






TCurrency Field 


Si 


Si 


Si 


Si 






TBCDField 


Si 


Si 


Si 


Si 






TFMTBCDField 


Si 


Si 


Si 


Si 






TDateTimeField 


Si 


Si 




Si 


Si 




TDateField 


Si 


Si 




Si 


Si 




TTimeField 


Si 


Si 




Si 


Si 




TSQLTimeStampField 


Si 


Si 




Si 


Si 
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TBooleanField 

TBytesField 

TVarBytesField 

TBlobField 

TMemoField 

TGraphicField 

TVariantField 

TAggregateField 





Ci 
Dl 






ji 


QV 
Dl 


ji 


Dl 


Si 


Si 


Si 


Si 


ND 


Si 


Si 


Si 



Si noti che alcune colonne nella tabella fanno riferimento a piu proprieta di 
conversione (come AsFloat, AsCurrency e AsBCD). Questo e il motivo per cui tutti i 
tipi di dati di campo che supportano una di quelle proprieta supportano sempre 
anche le altre. 

Si noti che la proprieta AsVariant puo anche tradurre di tutti i tipi di dati. Per tutti gli 
altri tipi di dati non elencati in precedenza, e disponibile anche AsVariant (ed e, 
infatti, Tunica opzione). In caso di dubbio, utilizzare AsVariant. 

In alcuni casi, le conversioni non sono possibili. Per esempio, AsDateTime puo essere 
utilizzato per convertire una stringa in un formato date, time o datetime solo se il 
valore della stringa e in un formato datetime riconoscibile. Un tentativo di 
conversione non riuscito genera un'eccezione. 

In alcuni altri casi, la conversione e possibile, ma i risultati non sono sempre intuitivi. 
Per esempio, che cosa significa convertire un valore TDateTimeField nel formato in 
virgola mobile? AsFloat converte la data riportata nel campo nel numero di giorni 
trascorsi dal 31/12/1899 e converte l'ora riportata nel campo in una frazione di 24 
ore. La Tabella 23.7 elenca le conversioni consentite che producono risultati speciali: 

Tabella 23.7 Risultati speciali di conversioni 
Conversione Risultato 

da String a Converte "True", "False", "Yes" e "No" in valore booleano. Gli altri valori 

Boolean sollevano eccezioni. 

da Float a Integer Arrotonda il valore in virgola mobile al valore intero piu vicino. 

da DateTime o Converte la data nel numero di giorni trascorsi dal 31 / 12/1899 e l'ora in una 
da frazione di 24 ore. 

SQLTimeStamp a 
Float 

da Boolean a Converte un valore booleano in "True" o "False." 

String 



Negli altri casi le conversioni non sono affatto possibili. In questi casi un eventuale 
tentativo di conversione solleva un'eccezione. 

La conversione si verifica sempre prima che l'assegnazione venga eseguita. Per 
esempio, la seguente istruzione converte il valore di Customer sCustNo in una stringa e 
assegna quest'ultima al testo di un controllo di testo: 

Editl->Text = CustomersCustNo->AsString; 
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Viceversa, la seguente istruzione assegna il testo di un controllo di testo come 
numero intero al campo Customer sCustNo: 

MyTableMyField->AsInteger = StrToInt (Editl->Text) ; 

Accesso ai valori dei campi con la proprieta predefinita del dataset 



II metodo piu indicate per accedere al valore di un campo e l'uso di Variant con la 
proprieta FieldValues. Ad esempio, la seguente istruzione inserisce il valore di una 
casella di testo nel campo CustNo della tabella Customers: 

Customers->FieldValues ["CustNo"] = Edit2->Text; 

Poiche la proprieta FieldValues e di tipo Variant, converte automaticamente gli altri 
tipi di dati in un valore Variant. 

Per ulteriori informazioni sui Variant, vedere la Guida in linea. 

Accesso ai valori dei campi con la proprieta Fields di un dataset 

E possibile accedere al valore di un campo con la proprieta Fields del componente 
dataset al quale il campo appartiene.FzeZds gestisce una lista indicizzata di tutti i 
campi nel dataset. L'accesso ai valori dei campi con la proprieta Fields e utile quando 
occorre elaborare in successione numerose colonne o quando l'applicazione lavora 
con tabelle non disponibili alio sviluppatore in fase di progetto. 

Per utilizzare la proprieta Fields, occorre conoscere l'ordine e i tipi di dati dei campi 
del dataset. Per specificare il campo cui accedere, si usa un numero ordinale. II primo 
campo di un dataset corrisponde al numero 0. 1 valori dei campi devono essere 
convertiti nel modo appropriato utilizzando le proprieta di conversione di ciascun 
componente campo. Per ulteriori informazioni sulle proprieta di conversione dei 
componenti campo, vedere "Conversione dei valori di campo" a pagina 23-19. 

Ad esempio, la seguente istruzione assegna il valore attivo della settima colonna 
(Country) della tabella Customers a un controllo di testo: 

Editl->Text = CustTable->Fields->Fields[6]->AsString; 

Viceversa, un valore puo essere assegnato a un campo impostando la proprieta Fields 
del dataset sul campo desiderato. Ad esempio: 

Customers->Edit ( ) ; 
Customers->Insert () ; 

Customers->Fields->Fields [6] ->AsString = Editl->Text ; 
Customers->Post ( ) ; 

Accesso ai valori dei campi con il metodo FieldByName di un dataset 



Per accedere al valore di un campo, e possibile anche ricorrere al metodo FieldByName 
di un dataset. Tael metodo risulta utile quando e noto il nome del campo a cui 
accedere ma non si ha accesso alia tabella sottostante in fase di progetto. 
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Per utilizzare FieldByName, e necessario conoscere il dataset e il nome del campo a cui 
accedere. II nome del campo viene passato come argomento del metodo. Per accedere 
al valore del campo o modificarlo, il risultato deve essere convertito con la proprieta 
appropriata per il componente campo, quale AsString o Aslnteger. Per esempio, la 
seguente istruzione assegna il valore del campo CustNo del dataset Customers a un 
controllo di testo: 

Edit2->Text = Customers->FieldByName( "CustNo" ) ->AsString; 

Viceversa, la seguente istruzione assegna un valore a un campo: 

Customers->Edit ( ) ; 

Customers->FieldByName ( "CustNo" )->AsString = Edit2->Text; 
Customers->Post () ; 

Impostazione del valore predefinito di un campo 



Grazie alia proprieta DefaultExpression, e possibile specificare il modo in cui dovrebbe 
essere calcolato in esecuzione il valore predefinito di un campo di un dataset client o 
di un dataset BDE. DefaultExpression puo essere qualsiasi espressione di valore SQL 
valida che non fa riferimento a valori di campo. Se l'espressione contiene letterali 
diversi da valori numerici, questi devono apparire tra virgolette. Ad esempio, il 
valore predefinito di mezzogiorno per un campo ora sarebbe 

'12:00:00' 

compresi gli apici che racchiudono il valore costante. 

Se la tabella del database sottostante stabilisce un valore predefinito per il campo, 
l'impostazione predefinita che si specifica in DefaultExpression ha la precedenza. 
Questo perche DefaultExpression viene applicato quando il dataset registra il record 
che contiene il campo, il che si verifica prima che il record modificato venga applicato 
al server di database. 

Utilizzo dei vincoli 



I componenti campo nei dataset client o nei dataset BDE possono utilizzare i vincoli 
dei server SQL. Inoltre, le applicazioni possono creare e usare vincoli custom per 
questi dataset che sono locali all'applicazione. Tutti i vincoli sono regole o condizioni 
che impongono un limite sulla visibilita o sull'intervallo dei valori che un campo puo 
contenere. 

Creazione di un vincolo custom 



Un vincolo custom non viene importato dal server come gli altri vincoli. E un vincolo 
che viene dichiarato, implementato e applicato in una applicazione locale. Come tali, 
i vincoli custom possono essere utili per consentire una preconvalida dei dati 
immessi, ma un vincolo custom non puo essere applicato a dati ricevuti da 
un'application server o ad esso inviati. 
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Per creare un vincolo custom, impostare la proprieta CustomConstraint specificando 
una condizione restrittiva e ConstraintErrorMessage specificando il messaggio da 
visualizzare quando un utente viola il vincolo in fase di esecuzione. 

CustomConstraint e una stringa SQL che specifica tutte i particolari vincoli imposti da 
un'applicazione sul valore del campo. Per limitare i valori che l'utente puo immettere 
in un campo, occorre impostare CustomConstraint. CustomConstraint puo essere 
qualsiasi espressione di ricerca SQL valida, come: 

x > and x < 100 

II nome usato per fare riferimento al valore del campo puo essere qualsiasi stringa 
che non sia una parola SQL riservata, purche lo si usi coerentemente in tutta 
l'espressione restrittiva. 

I vincoli custom sono solo disponibili solo nei dataset BDE e nei dataset client. 

I vincoli custom vengono imposti, in aggiunta a tutti gli altri vincoli, al valore del 
campo proveniente dal server. Per vedere i vincoli imposti dal server, consultare la 
proprieta ImportedConstraint. 

Uso dei vincoli del server 



La maggior parte dei database SQL di produzione usano vincoli per imporre 
condizioni sui possibili valori di un campo. Per esempio, un campo puo non 
consentire valori NULL, puo richiedere che il suo valore sia unico per quella colonna 
o che i suoi valori siano maggiori di e minori di 250. Benche sia possibile replicare 
tali condizioni nelle applicazioni client, i dataset client e i dataset BDE mettono a 
disposizione la proprieta ImportedConstraintper propagare localmente i vincoli di 
un server. 

ImportedConstraint e una proprieta a sola lettura che specifica una clausola SQL che 
limita i valori di campo in un determinato modo. Ad esempio: 

Value > and Value < 100 

Non si deve modificare il valore ImportedConstraint, tranne nei caso in cui si debbano 
modificare istruzioni SQL non standard o specifiche del server, importate come 
commento perche non interpretate dal motore di database. 

Per aggiungere altri vincoli sul valore del campo, usare la proprieta 
CustomConstraint. I vincoli custom vengono imposti in aggiunta ai vincoli importati. 
Se si modificano i vincoli del server, si modifica anche il valore di ImportedConstraint 
ma i vincoli immessi nella proprieta CustomConstraint persistono. 

La rimozione dei vincoli dalla proprieta ImportedConstraint non modifichera la 
validita dei valori di campo che violano quei vincoli. La rimozione dei vincoli implica 
che essi saranno controllati dal server anziche a livello locale. Quando i vincoli sono 
controllati localmente e si verifica una violazione della restrizione, invece di 
visualizzare un messaggio di errore proveniente dal server, verra visualizzato il 
messaggio di errore impostato tramite la proprieta ConstraintErrorMessage. 
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Uso dei campi oggetto 



I campi oggetto sono campi che rappresentano un insieme di altri tipi di dati piu 
semplici. Questi includono campi ADT (Abstract Data Type) campi Array, campi 
DataSet, e campi Reference. Questi tipi di campo contengono o fanno riferimento ai 
campi figlio e ad altri dataset. 

Un campo ADT e un campo array, contengono campi figlio. I campi figlio di un 
campo ADT possono essere un qualsiasi tipo scalare od oggetto (vale a dire, qualsiasi 
altro tipo di campo). II tipo di ognuno di questi campi figlio puo essere diverso da 
quello dell'altro. Un campo array contiene un array di campi figlio, tutti dello stesso 
tipo. 

I campi dataset e reference sono campi che accedono ad altri dataset. Un campo 
riferimento memorizza un puntatore (riferimento) a un altro oggetto persistente 
(ADT). 

Tabella 23.8 Tipi di componenti campo oggetto 



Nome del componente Funzione 



TADTField 


Rappresenta un campo ADT (Abstract Data Type). 


TArrayField 


Rappresenta un campo array. 


TDataSetField 


Rappresenta un campo che contiene un riferimento dataset 




annidato. 


TReferenceField 


Rappresenta un campo REF, un puntatore a un ADT. 



Quando si aggiungono campi con il Fields editor a un dataset contenente campi 
oggetto, vengono creati automaticamente i campi oggetto persistenti di tipo corretto. 
L'aggiunta di campi oggetto persistenti a un dataset imposta automaticamente la 
proprieta ObjectView del dataset a true, il che permette al dataset di memorizzare 
questi campi in ordine gerarchico, piuttosto che esplicitarli come se i campi figlio 
costituenti fossero campi separati e indipendenti. 

Le seguenti proprieta sono comuni a tutti i campi oggetto e forniscono le funzionalita 
per la gestione dei campi figlio e dei dataset. 



Tabella 23.9 Proprieta comuni dei discendenti dei campi oggetto 





Fields 


Contiene i campi figlio che appartengono al campo oggetto. 


ObjectType 


Classifica il campo oggetto. 


FieldCount 


Numero di campi figlio che appartengono al campo oggetto. 


FieldValues 


Fornisce l'accesso ai valori dei campi figlio. 



Visualizzazione di campi ADT e array 



Sia i campi ADT sia i campi array contengono campi figlio che possono essere 
visualizzati tramite controlli associati ai dati. 
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I controlli data-aware come TDBEdit che rappresentano un singolo valore di campo 
mostrano i valori dei campi figli campo una stringa delimitata con virgole non 
modificabile. Inoltre, se si imposta la proprieta DataField del controllo al campo figlio 
invece che alio stesso campo oggetto stesso, il campo figlio puo essere visualizzato e 
modificato esattamente come qualsiasi altro normale campo dati. 

Un controllo TDBGrid visualizza in modo diverso i campi ADT e i campi array, a 
seconda del valore della proprieta ObjectView del dataset. Quando ObjectView e false, 
ogni campo figlio appare in una colonna singola. Quando ObjectView e true, un 
campo ADT o un campo array possono essere espansi e ridotti facendo clic sulla 
freccia nella barra del titolo della colonna. Quando il campo viene espanso, ogni 
campo figlio appare nella propria colonna e barra del titolo, esattamente sotto la 
barra del titolo dello stesso ADT o array. Quando l'ADT o l'array viene ridotto, 
appare una sola colonna con una stringa non modificabile, delimitata da virgole, che 
contiene i campi figlio. 

Uso dei campi ADT 



Gli ADT sono tipi definiti dall'utente creati sul server e sono simili alle strutture. Un 
ADT puo contenere diversi tipi di campo scalari, campi array, campi riferimento e 
ADT annidati. 

Ci sono diversi modi per accedere ai dati nei tipi di campo ADT. Gli esempi seguenti 
assegnano un valore di campo figlio a una casella di modifica di nome CityEdit, e 
utilizzano la seguente struttura ADT: 

Address 
Street 
City 
State 
Zip 

Utilizzo di componenti campo persistenti 

II modo piu semplice per accedere a valori di un campo ADT consiste nell'utilizzare 
componenti campo persistenti. Per la struttura ADT vista in precedenza, e possibile 
aggiungere alia tabella Customer i seguenti campi persistenti utilizzando il Fields 
editor: 

CustomerAddress: TADTField; 
CustomerAddrStreet : TStringField; 
CustomerAddrCity : TStringField; 
CustomerAddrState: TStringField; 
CustomerAddrZip: TStringField; 

Dati questi campi persistenti, e possibile accedere semplicemente ai campi figlio di 
un campo ADT mediante il nome: 

CityEdit->Text = CustomerAddrCity->AsString; 

Benche i campi persistenti siano il modo piu semplice per accedere a campi figlio di 
ADT, non e possibile utilizzarli se, in fase di progettazione, non si conosce la struttura 
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del dataset. Quando si accede ai campi figli di ADT senza utilizzare campi 
persistenti, e necessario impostare a True la proprieta ObjectView del dataset. 

Utilizzo del metodo FieldByName del dataset 

E possibile accedere ai figli di un campo ADT utilizzando il metodo FieldByName del 
dataset, qualificando il nome del campo figlio con il nome del campo ADT: 

CityEdit->Text = Customer->FieldByName ( "Address . City" ) ->AsString; 

Utilizzo della proprieta FieldValues del dataset 

E possibile utilizzare nomi di campo qualificati anche con la proprieta FieldValues di 
un dataset: 

CityEdit->Text = Customer->FieldValues [ "Address .City" ] ; 

A differenza di altri metodi di esecuzione per accedere ai valori dei campo figlio di 
ADT, la proprieta FieldValues funziona anche se la proprieta ObjectView del dataset e 
impostata a false. 

Utilizzo della proprieta FieldValues del campo ADT 

Tramite la proprieta FieldValues di TADTField e possibile accedere al valore di un 
campo figlio. FieldValues accetta e restituisce un Variant, cosicche pud gestire e 
convertire campi di qualunque tipo. II parametro dell'indice e un valore integer che 
specifica lo scostamento del campo. 

CityEdit->Text = ( (TADTField* ) Customer->FieldByName ( "Address " ) ) ->FieldValues [1] ; 

Utilizzo della proprieta Fields del campo ADT 

Ogni campo ADT ha una proprieta Fields analoga alia proprieta Fields di un dataset. 
Come la proprieta Fields di un dataset, e possibile utilizzarla per accedere a campi 
figlio in base alia loro posizione: 

CityEdit->Text = ( (TADTField*) Customer->FieldByName ( "Address " ) ) ->Fields-> 
Fields [l]->AsString; 

oppure in base al nome: 

CityEdit->Text = ( (TADTField*) Customer->FieldByName ( "Address " ) )-> 
Fields->FieldByNarae ( "City" ) ->AsString; 

Uso dei campi array 



I campi array sono costituiti da un gruppo di campi dello stesso tipo. II tipo di campo 
puo essere scalare (per esempio, float o string), o non scalare (un ADT), ma non pud 
essere un campo array di array. La proprieta SparseArrays di TDataSet determina se 
per ciascun elemento del campo array viene creato un oggetto TField univoco. 

Esistono diversi modi per accedere ai dati nei tipi di campo array. Se non si utilizzano 
campi persistenti, prima di potere accedere agli elementi di un campo array e 
necessario impostare a True la proprieta ObjectView del dataset. 
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Utilizzo di campi persistenti 

E possibile mappare i campi persistenti su singoli elementi dell'array di un campo 
array. Ad esempio, si prenda in esame un campo array TelNos_Array, che e un array di 
stringhe con sei elementi. I campi persistenti seguenti, creati per il componente 
tabella Customer, rappresentano il campo TelNos_Array e i suoi sei elementi: 

CustornerTELNOS_ARRAY: TArrayField; 

CustornerTELNOS_ARRAY0 : TStringField; 

CustornerTELNOS_ARRAYl : TStringField; 

CustomerTELN0S_ARRAY2 : TStringField; 

CustomerTELN0S_ARRAY3 : TStringField; 

CustomerTELN0S_ARRAY4 : TStringField; 

CustomerTELN0S_ARRAY5 : TStringField; 

Dati questi campi persistenti, il seguente codice utilizza un campo persistente per 
assegnare il valore di un elemento dell'array a una casella di testo di nome TelEdit. 

TelEdit->Text = CustomerTELNOS_ARRAY0->AsString; 

Uso della proprieta FieldValues del campo array 

Tramite la proprieta FieldValues del campo array e possibile accedere al valore di un 
campo figlio. FieldValues accetta e restituisce un Variant, pertanto puo gestire e 
convertire campi di qualunque tipo. Ad esempio: 

TelEdit->Text = ( (TArrayField*) Customer->FieldByName ( "TelNosJvrray" ) ) ->FieldValues [1] ; 

Uso della proprieta Fields del campo array 

TArrayField ha una proprieta Fields che e possibile utilizzare per accedere ai singoli 
sottocampi. II procedimento e illustrato nel codice seguente, in cui un campo array 
(OrderDates) viene utilizzato per riempire una casella di riepilogo con elementi di 
array non nulli: 

for (int 1 = 0; i < OrderDates->Size; ++i) 
if ( !OrderDates->Fields->Fields [i] ->lsNull) 
OrderDateListBox->ltems->Add(OrderDates->Fields->Fields [i] ->AsString) ; 

Uso dei campi dataset 



I campi dataset forniscono l'accesso ai dati memorizzati in un dataset annidato. La 
proprieta NestedDataSet referenzia il dataset annidato. Ai dati del dataset annidato si 
puo poi accedere tramite gli oggetti campo del dataset stesso. 

Visualizzazione dei campi dataset 

I controlli TDBGrid consentono la visualizzazione dei dati memorizzati nei campi del 
dataset. In un controllo TDBGrid, un campo del dataset viene indicato in ciascuna 
cella di una colonna del dataset mediante la stringa "(DataSet)" e, in fase di 
esecuzione, alia destra del campo appare anche un pulsante ellissi. Facendo clic sul 
pulsante si richiama una nuova scheda con una griglia che visualizza il dataset 
associato al campo dataset del record attivo. Questa scheda puo anche essere 
richiamata da programma con il metodo ShowPopupEditor della griglia DB. Per 
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esempio, se la settima colonna della griglia rappresenta un campo dataset, il codice 
seguente visualizzera il dataset associato a quel campo per il record attivo. 

DBGridl->ShowPopupEditor(DBGridl->Columns->Items [7] , -1, -1) ; 

Accesso ai dati in un dataset annidato 

Di solito un campo di un dataset non e collegato direttamente a un controllo associato 
ai dati. Piuttosto, poiche un dataset annidato non e altro che un dataset, il mezzo per 
accedere ai dati in esso contenuti e tramite un discendente di TDataSet. II tipo di 
dataset che si utilizza e determinate dal dataset genitore (quello con il campo 
dataset). Ad esempio, un dataset BDE utilizza TNestedTable per rappresentare i dati 
nei campi del proprio dataset, mentre i dataset client utilizzano altri dataset client. 

Per accedere ai dati in un campo dataset: 

1 Creare un oggetto persistente TDataSetField richiamando il Fields editor per il 
dataset genitore. 

2 Creare un dataset per rappresentare i valori in quel campo dataset. Deve essere di 
un tipo compatibile con il dataset genitore. 

3 Impostare la proprieta DataSetField del dataset creato al punto 2 al campo dataset 
persistente creato al punto 1. 

Se il campo dataset annidato del record corrente ha un valore, il componente dataset 
di dettaglio conterra record con dati annidati; in caso contrario, il dataset di dettaglio 
sara vuoto. 

Before inserting records into a nested dataset, you should be sure to post the 
corresponding record in the master table, if it has just been inserted. If the inserted 
record is not posted, it will be automatically posted before the nested dataset. 

Uso dei campi riferimento 



I campi riferimento memorizzano un puntatore o un riferimento a un altro oggetto 
ADT. Questo oggetto ADT e un singolo record di un'altra tabella oggetto. I campi 
riferimento si riferiscono sempre a un unico record di un dataset (tabella oggetto). I 
dati dell'oggetto referenziato vengono di fatto restituiti in un dataset annidato, ma e 
possibile accedervi tramite la proprieta Fields in TReferenceField. 

Visualizzazione dei campi riferimento 

In un controllo TDBGrid, un campo riferimento viene rappresentato, in ciascuna cella 
della colonna del dataset, con la scritta (Reference) e, in fase di esecuzione, tramite un 
pulsante con puntini di sospensione a destra. In fase di esecuzione, facendo clic sul 
pulsante si richiama una nuova scheda con una griglia che visualizza l'oggetto 
associato al campo riferimento del record attivo. 

Questa scheda puo anche essere richiamata da programma con il metodo 
ShowPopupEditor della griglia DB. Per esempio, se la settima colonna della griglia 
rappresenta un campo riferimento, il codice seguente visualizzera l'oggetto associato 
a quel campo per il record attivo. 
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DBGridl->ShowPopupEditor(DBGridl->Columns->Items [7] , -1, -1) ; 

Accesso ai dati di un campo riferimento 

E possibile accedere ai dati in un campo riferimento in modo analogo a quello 
utilizzato per accedere a un dataset annidato: 

1 Creare un oggetto persistente TDataSetField richiamando il Fields editor per il 
dataset genitore. 

2 Creare un dataset per rappresentare il valore di quel campo di dataset. 

3 Impostare la proprieta DataSetField del dataset creato al punto 2 al campo dataset 
persistente creato al punto 1. 

Se il riferimento e assegnato, il dataset conterra un unico record con i dati 
referenziati. Se e nullo, il dataset di riferimento sara vuoto. 

E possibile anche utilizzare la proprieta Fields del campo riferimento per accedere ai 
dati in un campo riferimento. L'esempio seguente assegna i dati del campo 
riferimento CustomerRefCity a una casella di modifica di nome CityEdit: 

CityEdit->Text = CustomerADDRESS_REF->NestedDataSet->Fields->Fields [1] ->AsString; 

Quando si modificano i dati in un campo riferimento, di fatto vengono modificati i 
dati referenziati. 

Per assegnare un campo riferimento, bisogna prima usare un'istruzione SELECT per 
selezionare il riferimento dalla tabella. Ad esempio: 

AddressQuery->SQL->Text = " SELECT REF(A) FROM AddressTable A WHERE A. City = 'San 
Francisco 1 11 ; 
AddressQuery->Open ( ) ; 

CustomerAddressRef->Assign(AddressQuery->Fields->Fields [0] ) ; 
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Uso di Borland Database Engine 

Borland Database Engine (BDE) e un meccanismo di accesso ai dati condivisibile da 
piu applicazioni. Definisce una potente libreria di chiamate API che servono a creare, 
a ristrutturare, a prelevare dati da server di database locali e remoti, ad aggiornarli o 
comunque a manipolarli. BDE offre un'interfaccia uniforme per l'accesso a un'ampia 
varieta di server di database, utilizzando dei driver per collegarsi a vari database. A 
seconda della versione di C++Builder disponibile, si utilizzeranno i driver per 
database locali (Paradox, dBASE, FoxPro e Access), i driver SQL Links per server di 
database remoti come InterBase, Oracle, Sybase, Informix, server Microsoft SQL e 
DB2, piu un adattatore ODBC che consente di fornire driver ODBC realizzati in 
proprio. 

Per la distribuzione di applicazioni BDE, e necessario distribuire BDE con 
l'applicazione. La dimensione e la complessita dell'applicazione aumentano, ma 
sono possibili sia l'uso condiviso con altre applicazioni BDE sia un'ampia gamma di 
funzioni ausiliarie per la manipolazione dei database. Benche sia possibile utilizzare 
l'API di BDE direttamente nelle applicazioni, i componenti alia pagina BDE della 
Component palette si incaricano di svolgere la maggior parte di queste funzionalita . 

Per informazioni sull'API BDE, consultare il file di guida in linea, BDE32.hlp, che si 
trova nella directory dove e stato installato Borland Database Engine. 

Larchitettura BDE 



Le applicazioni che utilizzano BDE sfruttano una variante dell'architettura generale 
di database descritta in "Architettura di un database" a pagina 18-6. Oltre agli 
elementi dell'interf accia utente, al datasource e ai dataset comuni a tutte le 
applicazioni database C++Builder , le applicazioni BDE possono comprendere 

• Uno o piu componenti database per il controllo delle transazioni e la gestione delle 
connessioni con il database. 
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• Uno o piu componenti session per isolare le operazioni di accesso ai dati come le 
connessioni con il database e la gestione di gruppi di database. 

Le relazioni tra i componenti di un'applicazione BDE sono illustrate in Figura 24.1: 

Figura 24.1 Componenti in un'applicazione BDE 




Form Data Module 



Impiego di dataset per BDE 



I dataset utilizzano Borland Database Engine (BDE) per accedere ai dati. Essi 
ereditano le funzionalita dei dataset comuni descritte in Capitolo 22, "I dataset", 
mentre sfruttano BDE per l'implementazione. Inoltre, tutti i dataset per BDE 
aggiungono proprieta , eventi e metodi per le seguenti funzioni: 

• Associazione di un dataset a connessioni di database e di sessione. 

• Cache dei BLOB. 

• Ottenimento degli handle BDE. 

Ci sono tre dataset per BDE: 

• TTable, un dataset di tipo tabella che rappresenta tutte le righe e le colonne di una 
singola tabella di database. Per la descrizione delle funzioni comuni ai dataset 
tabellari fare riferimento a "Utilizzo dei dataset di tipo tabella" a pagina 22-26. Per 
la descrizione delle funzioni univoche a TTable, fare riferimento a "Utilizzo di 
TTable" a pagina 24-5. 

• TQuery, un dataset di tipo query che incorpora un'istruzione SQL e permette alle 
applicazioni di accedere ai record risultanti, se esistono. Consultare "Utilizzo di 
dataset di tipo query" a pagina 22-43 per la descrizione delle funzioni comuni ai 
dataset di tipo query. Consultare "Utilizzo di TQuery" a pagina 24-9 per la 
descrizione delle funzioni speciali di TQuery. 

• TStoredProc, un dataset di tipo procedura registrata che esegue una procedura 
registrata definita su un server di database. Consultare "Utilizzo di dataset di tipo 
procedura registrata" a pagina 22-52 per una descrizione delle funzioni comuni ai 
dataset di tipo procedura registrata. Per la descrizione delle funzioni uniche di 
TStoredProc consultare "Utilizzo di TStoredProc" a pagina 24-12. 

Oltre ai tre tipi di dataset per BDE, esiste un dataset client basato su BDE 
(TBDEClientDataSet) utilizzabile per la gestione degli aggiornamenti in cache. Per le 
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informazioni relative, consultare "Utilizzo di un dataset client per registrare in cache 
gli aggiornamenti" a pagina 27-17. 

Associazione di un dataset a connessioni di database e di sessione 

Per prelevare i dati da un server di database, i dataset BDE utilizzano sia un database 
che una sessione. 

• I database rappresentano connessioni a specifici server di database. II database 
identifica un certo driver BDE, un particolare server di database che lo utilizza, e 
un set di parametri per la connessione al server di database. Ogni database e 
rappresentato da un componente TDatabase. Si possono associare i dataset a un 
componente TDatabase che viene aggiunto a una scheda o a un modulo dati, 
oppure semplicemente, si identifica il server di database tramite il nome e si lascia 
che sia C++Builder a generare un componente database implicito. L'impiego di 
componenti TDatabase creati esplicitamente e raccomandato nella maggior parte 
delle applicazioni, perche essi consentono di controllare meglio le modalita di 
connessione, compreso il processo di login, e permettono al programmatore di 
creare e di utilizzare le transazioni. 

Per associare un dataset per BDE a un database, si ricorre alia proprieta 
DatabaseName. DatabaseName e una stringa contenente informazioni diverse, a 
seconda che si utilizzi un componente database esplicito, oppure, in caso 
contrario, il tipo di database che si utilizza: 

• Se si utilizza un componente esplicito TDatabase, DatabaseName e il valore della 
sua proprieta DatabaseName. 

• Se si vuole usare un componente database implicito, e il database ha un alias 
BDE, si pud specificare, l'alias BDE come valore di DatabaseName,. Un alias BDE 
rappresenta un database, piu informazioni relative alia sua configurazione. Le 
informazioni di configurazione associate a un alias sono diverse a seconda del 
tipo di database (Oracle, Sybase, InterBase, Paradox, dBASE e cosi via). Per 
creare e gestire gli alias BDE si ricorre alio strumento BDE Administration o a 
SQL Explorer. 

• Volendo utilizzare un componente database implicito con un database Paradox 
o dBASE, e possibile anche ricorrere a DatabaseName e specificare 
semplicemente la directory dove sono situate le tabelle di database. 

• In un'applicazione, una sessione fornisce la gestione globale di un gruppo di 
connessioni di database. Quando all'applicazione si aggiungono dei dataset BDE, 
questa conterra automaticamente un componente session, chiamato Session. II 
database e i componenti dataset aggiunti all'applicazione sono associati 
automaticamente a questa sessione predefinita. Viene anche controllato l'accesso 
ai file Paradox protetti da password e vengono specificate le directory per la 
condivisione di file Paradox in rete. Le connessioni al database e l'accesso ai file 
Paradox si controllano utilizzando le proprieta , gli eventi e i metodi della 
sessione. 

Si pud utilizzare la sessione predefinita per controllare tutte le connessioni al 
database nell'applicazione. In alternativa, si aggiungono ulteriori componenti in 
progettazione o si creano dinamicamente in esecuzione per controllare un 
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sottoinsieme di connessioni al database. Per associare il dataset a un componente 
session esplicitamente creato, si ricorre alia proprieta SessionName. Se 
nell'applicazione non si utilizzano componenti session espliciti, non e necessario 
fornire il valore di questa proprieta . Se si utilizza la sessione predefinita, o si 
specifica esplicitamente una sessione mediante la proprieta SessionName, e 
possibile accedere alia sessione associata a un dataset leggendo la proprieta 
DBSession. 

Se si utilizza un componente session, la proprieta SessionName di un dataset deve 
corrispondere alia proprieta SessionName del componente database a cui il dataset e 
associato. 

Per ulteriori informazioni su TDatabase e su TSession, consultare "Collegamento ai 
database tramite TDatabase" a pagina 24-13 e "Gestione delle sessioni di database" a 
pagina 24-17. 

Cache dei BLOB 

I dataset BDE hanno tutti una proprieta CacheBlobs che controlla se BDE registra a 
livello locale i campi, quando un'applicazione legge i record BLOB. Per impostazione 
predefinita, CacheBlobs e true, il che significa che BDE memorizza nella cache una 
copia locale dei campi BLOB. La registrazione nella cache dei campi BLOB migliora 
le prestazioni dell'applicazione in quanto BDE memorizza localmente le copie dei 
BLOB, invece di prelevarli ripetutamente dal server di database mano a mano che 
l'utente fa scorrere i record. 

Nelle applicazioni e negli ambienti dove i BLOB si aggiornano o si sostituiscono 
spesso e dove una vista fresca dei dati BLOB e piu importante delle prestazioni, e 
possibile impostare CacheBlobs a false per assicurarsi che venga sempre vista la 
versione piu recente di un campo BLOB. 

Ottenimento degli handle BDE 

E possibile utilizzare dei dataset per BDE senza fare chiamate dirette alia API di 
Borland Database Engine. I dataset per BDE, combinati con componenti database e di 
sessione, incorporano molte funzionalita BDE. Tuttavia, se e necessario fare chiamate 
dirette alia API di BDE, per le risorse gestite da BDE servono gli handle BDE. Molte 
API BDE richiedono questi handle come parametri. 

Tutti i dataset per BDE includono tre proprieta a sola lettura per l'accesso in fase di 
esecuzione agli handle BDE: 

• Handle e un handle al cursor BDE che accede ai record nel dataset. 

• DBHandle e un handle al database che contiene le tabelle o la procedura registrata 
relative. 

• DBLocale e un handle al driver BDE del linguaggio del dataset e controlla la 
sequenza di ordinamento e il set di caratteri utilizzati per i dati di stringa. 

Queste proprieta sono assegnate automaticamente a un dataset quando questo si 
collega a un server di database tramite BDE. Per ulteriori informazioni sulla API di 
BDE, consultare il file della guida in linea, BDE32.HLP. 
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Utilizzo di TTable 



TTable incapsula la struttura completa e i dati in una tabella di database e 
implementa tutte le funzionalita di base introdotte da TDataSet, come pure tutte le 
funzioni speciali tipiche dei dataset di tipo tabella. Prima di analizzare le funzionalita 
esclusive di TTable, conviene familiarizzare con le funzionalita comuni dei database 
descritte in "I dataset", compresa la sezione sui dataset tabellari che inizia a 
pagina 22-26. 

TTable e un dataset per BDE, e quindi deve essere associato a un database e a una 
sessione. II paragrafo "Associazione di un dataset a connessioni di database e di 
sessione" a pagina 24-3 spiega come si formano queste associazioni. Una volta che il 
dataset e associato a un database e a una sessione, e possibile legarlo a una 
particolare tabella di database impostando la proprieta TableName e, se si utilizza una 
tabella di testo ASCII Paradox, dBASE, FoxPro o comma-delimited, alia proprieta 
TableType. 

La tabella deve essere chiusa quando si modifica la sua associazione a un database, a 
una sessione o a una tabella di database, o quando si imposta la proprieta TableType. 
Tuttavia, prima di chiudere la tabella per modificare queste proprieta , bisogna 
registrare o annullare le modifiche in attesa. Se sono abilitati gli aggiornamenti in 
cache, bisogna chiamare il metodo Applyllpdates per scrivere nel database le 
modifiche richieste. 

I componenti TTable offrono un supporto ineguagliabile per la gestione delle tabelle 
di database locali (Paradox, dBASE, FoxPro e tabelle di testo ASCII comma- 
delimited). Qui di seguito sono riportati le proprieta e i metodi speciali che 
implementano questo supporto. 

Inoltre, i componenti TTable possono sfruttare il supporto BDE per le operazioni in 
batch (operazioni a livello di tabella per aggiungere, aggiornare, cancellare o copiare 
interi gruppi di record). L'argomento e trattato in "Importazione di dati da altre 
tabelle" a pagina 24-8. 

Specifica del tipo di tabella per tabelle locali 

Se un'applicazione accede a tabelle Paradox, dBASE, FoxPro o di testo ASCII comma- 
delimited, allora BDE utilizza la proprieta TableType per determinare il tipo di tabella 
(la sua struttura prevista). TableType non viene usato quando TTable rappresenta una 
tabella a base SQL su un server di database. 

Per impostazione predefinita, TableType e impostato a HDefault. In questo caso, BDE 
determina il tipo di tabella dalla sua estensione. La Tabella 24.1 riporta le estensioni 
riconosciute da BDE, e le ipotesi che fa sul tipo della tabella: 

Tabella 24.1 Tipi di tabella riconosciuti da BDE in base all'estensione del file 
Estensione Tipo di tabella 

No file extension Paradox 
.DB Paradox 
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Tabella 24.1 Tipi di tabella riconosciuti da BDE in base all'estensione del file (continua) 



Estensione 


Tipo di tabella 


.DBF 


dBASE 


.TXT 


ASCII text 


Se le tabelle di testo Paradox, dBASE e ASCII locali utilizzano le estensioni file come 
descritto in Tabella 24.1, e possibile lasciare TableType impostato su ttDefault. 
Altrimenti, l'applicazione deve impostare TableType in modo da indicare il tipo di 
tabella corretto. In Tabella 24.2 sono indicati i valori che e possibile assegnare a 
TableType: 


Tabella 24.2 Valori di TableType 


Valore 


Tipo di tabella 


ttDefault 


Tipo di tabella determinato automaticamente da BDE 


ttParadox 


Paradox 


ttDBase 


dBASE 


ttFoxPro 


FoxPro 


ttAscn 


Testo ASCII Comma-delimited 



Controllo dell'accesso a tabelle locali in lettura/scrittura 

Come qualsiasi dataset di tipo tabella, TTable permette di controllare l'accesso in 
lettura e in scrittura da parte dell'applicazione tramite la proprieta ReadOnly. 

Inoltre, nel caso di tabelle Paradox, dBASE e FoxPro, TTable consente di controllare 
l'accesso in lettura e in scrittura alle tabelle da parte di altre applicazioni. La 
proprieta Exclusive determina se l'applicazione ottiene l'accesso esclusivo in lettura/ 
scrittura a una tabella Paradox, dBASE o FoxPro. Alio scopo, si imposta a true la 
proprieta Exclusive del componente tabella prima di aprire la tabella. Se si riesce ad 
aprire una tabella per accesso esclusivo, le altre applicazioni non possono ne leggere 
ne scrivere dati nella tabella. La richiesta di accesso esclusivo non viene concessa 
quando la tabella e gia in uso. 

Le seguenti istruzioni aprono una tabella per accesso esclusivo: 

CustomersTable->Exclusive = true; // Set request for exclusive lock 
CustomersTable->Active = true; // Now open the table 

E possibile tentare di impostare la proprieta Exclusive su tabelle SQL, ma alcuni 
server non supportano il blocco esclusivo a livello di tabella. Altri server concedono il 
blocco esclusivo, ma consentono ad altre applicazioni di leggere i dati dalla tabella. 
Per ulteriori informazioni sul blocco esclusivo di tabelle di database su un server, 
consultare la documentazione del server. 

Specifica di file indice dBASE 

Nella maggior parte dei server, per specificare un indice si utilizzano i metodi 
comuni a tutti i dataset tabellari, descritti in "Ordinamento dei record con indici" a 
pagina 22-27. 
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Tuttavia, per le tabelle dBASE che utilizzano file indice aggiunti, oppure indici tipo 
dBASE III PLUS (*.NDX), e necessario invece utilizzare le proprieta IndexFiles e 
IndexName. Alia proprieta IndexFiles si assegna il nome del file indice aggiunto, o si 
elencano i file.NDX. Poi si specifica un indice nella proprieta IndexName per fare in 
modo che ordini attivamente il dataset. 

In fase di progetto, si fa clic sul pulsante ellissi (...)nel valore della proprieta IndexFiles 
di Object Inspector per richiamare l'lndex Files editor. Per aggiungere un file indice 
aggiunto o un file .NDX si fa clic sul pulsante Add nella finestra di dialogo Index 
Files e si seleziona il file nella finestra di dialogo Open. La procedura va ripetuta per 
ogni file indice non di produzione o .NDX. Dopo avere aggiunto tutti gli indici 
desiderati si fa clic sul pulsante OK della finestra di dialogo Index Files. 

La stessa operazione puo essere eseguita da programma in fase di esecuzione. Alio 
scopo, si accede alia proprieta IndexFiles utilizzando le proprieta e i metodi delle liste 
di stringhe. Quando si aggiunge un nuovo gruppo di indici, prima si chiama il 
metodo Clear della proprieta IndexFiles della tabella per rimuovere eventuali voci 
inserite. Si chiama il metodo Add per aggiungere ogni file indice non di produzione o 
file .NDX: 

Table2->lndexFiles->Clear() ; 
Table2->IndexFiles->Add( "Bystate.ndx" ) ; 
Table2->IndexFiles->Add( "Byzip.ndx" ) ; 
Table2->lndexFiles->Add("Fullname.ndx" ) ; 
Table2->lndexFiles->Add( "St_name.ndx" ) ; 

Dopo avere aggiunto gli eventuali file indice non di produzione o .NDX, diventano 
disponibili i nomi dei singoli indici nel file indice ed e possibile assegnarli alia 
proprieta IndexName. I tag indice vengono elencati anche quando si utilizza il metodo 
GetlndexNames ed quando si esaminano le definizioni di indice attraverso gli oggetti 
TIndexDef nella proprieta IndexDefs. I file .NDX elencati correttamente vengono 
aggiornati automaticamente mano a mano che i dati vengono aggiunti, modificati o 
cancellati nella tabella (indipendentemente dal fatto che la proprieta IndexName 
utilizzi o meno un certo indice). 

Nell'esempio qui riportato, il componente IndexFiles del componente tabella 
AnimalsTable e impostato al file indice non di produzione ANIMALS. MDX e quindi 
la sua proprieta IndexName e impostata al tag indice chiamato "NAME": 

AnimalsTable->IndexFiles->Add ( "ANIMALS .MDX" ) ; 
AnimalsTable->IndexName = "NAME"; 

Una volta che si e specificato il file indice, l'utilizzo di indici non di produzione o 
.NDX non differisce da quello di qualsiasi altro indice. Specificando un nome indice 
si ordinano i dati nella tabella rendendoli disponibili per ricerche indicizzate, per 
intervalli e (nel caso di indici non di produzione) per collegamenti master-detail. Per 
i dettagli su questo modo di usare gli indici, consultare "Utilizzo dei dataset di tipo 
tabella" a pagina 22-26. 

Quando si utilizzano indici .NDX, in stile dBASE III, con componenti TTable vanno 
tenute presenti due considerazioni particolari. La prima e che i file .NDX non si 
possono usare come base per collegamenti master-detail. La seconda e che quando si 
attiva un indice .NDX con la proprieta IndexName, e necessario includere l'estensione 
.NDX nel valore della proprieta come parte del nome dell'indice: 
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Tablel->lndexName = "ByState.NDX" ; 
TVarRec vr = ( "NE" ) ; 
Tablel->FmdKey (&vr, 0); 

Come rinominare ta belle locali 

Per rinominare in fase di progettazione le tabelle Paradox o dBASE, si fa clic con il 
pulsante destro sul componente tabella e si seleziona Rename Table nel menu di 
scelta rapida. 

Per rinominare in fase di esecuzione le tabelle Paradox o dBASE, si chiama il metodo 
RenameTable della tabella. Ad esempio, con la seguente istruzione si rinomina la 
tabella Customer in Custlnfo: 

Customer->RenameTable ( "Custlnfo" ) ; 

Importazione di dati da altre tabelle 

Per importare dati da un'altra tabella si utilizza il metodo BatchMove di un 
componente tabella. BatchMove puo 

• Copiare nella tabella attiva dei record da un'altra tabella. 

• Aggiornare nella tabella attiva dei record che si trovano in un'altra tabella. 

• Aggiungere alia fine della tabella attiva dei record di un'altra tabella. 

• Cancellare nella tabella attiva dei record che si trovano in un'altra tabella. 

BatchMove accetta due parametri: il nome della tabella da cui importare i dati e una 
specifica di modo che determina quale operazione di importazione eseguire. La 
Tabella 24.3 mostra le possibili impostazioni della specifica di modo: 

Tabella 24.3 Modalita di importazione di BatchMove 
Valore Significato 

batAppend Aggiunge tutti i record dalla tabella sorgente alia fine della tabella attiva. 

batAppendUpdate Aggiunge tutti i record dalla tabella sorgente alia fine della tabella attiva e 
aggiorna nella tabella attiva i record esistenti con record corrispondenti 
della tabella sorgente. 

batCopy Copia nella tabella attiva tutti i record della tabella sorgente. 

batDelete Cancella tutti i record della tabella attiva presenti anche nella tabella 

sorgente. 

batUpdate Aggiorna i record esistenti nella tabella attiva con record corrispondenti 

della tabella sorgente. 

Ad esempio, con questo codice si aggiornano tutti i record della tabella attiva con 
record della tabella Customer che hanno gli stessi valori per i campi dell'indice attivo: 

Tablel->BatchMove( "CUSTOMER. DB", batUpdate) ; 

BatchMove restituisce il numero di record importati con successo. 

Importando record con il modo batCopy si sovrascrivono i record esistenti. Per 
conservarli si ricorre invece a batAppend. 
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BatchMove esegue solo alcune delle operazioni batch supportate da BDE. II 
componente TBatchMove dispone di ulteriori funzioni. Se e necessario spostare una 
grande quantita di dati tra tabelle, e preferibile utilizzare TBatchMove invece di 
chiamare un metodo BatchMove. Per informazioni sull'utilizzo di TBatchMove, 
consultare "Utilizzo di TBatchMove" a pagina 24-50. 

Utilizzo di TQuery 



TQuery rappresenta una singola istruzione Data Definition Language (DDL) o Data 
Manipulation Language (DML) (ad esempio, un comando SELECT, INSERT, 
DELETE, UPDATE, CREATE INDEX o ALTER TABLE). II linguaggio nei comandi 
dipende dal server, ma di solito e conforme alio standard SQL-92 del linguaggio 
SQL. TQuery implementa tutte le funzionalita di base introdotte da TDataSet, come 
pure tutte le funzionalita speciali tipiche dei dataset di tipo query. Prima di 
analizzare le funzionalita esclusive di cui TQuery dispone, e bene prendere 
familiarita con le funzioni database fondamentali descritte in "I dataset", tra cui la 
sezione sui dataset di tipo query che inizia a pagina 22-43. 

Siccome TQuery e un dataset per BDE, si deve di solito associarlo a un database e a 
una sessione. (L'unica eccezione e quando si utilizza TQuery per una query 
eterogenea). II paragrafo "Associazione di un dataset a connessioni di database e di 
sessione" a pagina 24-3 descrive come si formano queste associazioni. Si specifica 
l'istruzione SQL della query impostando la proprieta SQL. 

Un componente TQuery puo accedere a dati in: 

• Tabelle Paradox o dBASE, utilizzando Local SQL, che fa parte di BDE. Local SQL e 
un sottoinsieme delle specifiche SQL-92. Supporta la maggior parte del DML e una 
porzione di DDL sufficiente a funzionare con questi tipi di tabelle. Per i dettagli 
sulla sintassi SQL supportata, consultare la guida SQL locale, LOCALSQL.HLP.. 

• Database locali InterBase Server, utilizzando il motore InterBase. Per informazioni 
sul supporto della sintassi SQL standard e della sintassi estesa SQL-92 di 
InterBase, consultare Language Reference di InterBase. 

• Database su server di database remoti come Oracle, Sybase, MS-SQL Server, 
Informix, DB2 e InterBase. Per accedere a un server remoto e necessario installare 
il driver SQL Link e appropriato e il software client (fornito dal produttore) 
specifico per il server di database. Viene accettata qualsiasi sintassi standard SQL 
supportata da questi server. Per informazioni sulla sintassi SQL, sulle sue 
limitazioni ed estensioni, fare riferimento alia documentazione del server in 
questione. 

Creazione di query eterogenee 

TQuery supporta query eterogenee verso piu server o piu tipi di tabella (ad esempio, 
dati da una tabella Oracle e da una tabella Paradox). Quando si esegue una query 
eterogenea, BDE analizza ed elabora la query utilizzando Local SQL e per questa 
ragione non e supportata la sintassi SQL specifica del server. 

Per eseguire una query eterogenea, seguire questi passi: 
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1 Definire alias BDE distinti per ogni database cui si deve accedere nella query 
utilizzando lo strumento BDE BDE Administration o SQL Explorer. 

2 Lasciare in bianco la proprieta DatabaseName di TQuery; i nomi dei database 
utilizzati saranno specificati nell'istruzione SQL. 

3 Nella proprieta SQL, specificare l'istruzione SQL da eseguire. Far precedere ogni 
nome di tabella nell'istruzione con l'alias BDE del database della tabella, racchiuso 
tra segni di due punti. L'intero riferimento viene poi racchiuso tra virgolette. 

4 Impostare i parametri della query nella proprieta Params. 

5 Chiamare Prepare per preparare la query all' esecuzione prima di eseguirla per la 
prima volta. 

6 Chiamare Open o ExecSQL, a seconda del tipo di query che si esegue. 

Ad esempio, si supponga di definire un alias chiamato Oraclel per un database 
Oracle che ha una tabella CUSTOMER e Sybasel per un database Sybase che ha una 
tabella ORDERS. Una semplice query verso queste due tabelle sarebbe: 

SELECT Customer. CustNo, Orders .OrderNo 
FROM ": Oraclel: CUSTOMER" 
JOIN ": Sybasel: ORDERS" 
ON (Customer. CustNo = Orders .CustNo) 
WHERE (Customer. CustNo = 1503) 

Come alternativa all'utilizzo di un alias BDE per specificare il database in una query 
eterogenea, si puo utilizzare un componente TDatabase. Configurare il TDatabase 
come normale per puntare al database, impostare il TDatabase.DatabaseName a un 
valore arbitrario ma univoco, quindi utilizzarlo nell'istruzione SQL al posto del nome 
dell'alias BDE. 

Ottenimento di un set risultato modificabile 

Per richiedere un set risultato che gli utenti possono editare in controlli data-aware, 
impostare a true la proprieta RequestLive di un componente query. L'impostazione di 
RequestLive a true non garantisce un set risultato "live" ma BDE fa il possibile per 
rispettare la richiesta. Le richieste di set risultato "live" sono soggette ad alcune 
limitazioni, a seconda che la query utilizzi il parser locale SQL, o un parser SQL del 
server. 

• Le query in cui i nomi di tabella sono preceduti da un alias di database BDE (come 
nelle query eterogenee) e le query eseguite verso Paradox o dBASE, sono 
analizzate da BDE utilizzando Local SQL. Quando le query utilizzano il parser di 
Local SQL, BDE offre un supporto esteso per set risultato aggiornabili e "live" sia 
nelle tabelle singole che nelle query multitabella. Quando si utilizza Local SQL, 
una query su una singola tabella o vista restituisce un set risultato "live" se non 
contiene: 

• DISTINCT nella clausola SELECT 

• Join (interno, esterno, o UNION) 

• Funzioni di aggregazione con o senza clausole GROUP BY o HAVING 

• Tabelle o viste base non aggiornabili 

• Sottoquery 
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• Clausole ORDER BY non basate su un indice 

• Le query verso un server di database remoto vengono analizzate dal server. Se la 
proprieta RequestLive e impostata a true, l'istruzione SQL deve attenersi agli 
standard Local SQL, oltre a rispettare tutte le limitazioni imposte dal server, 
perche BDE deve utilizzarla per convogliare alia tabella i dati modificati. Una 
query su una singola tabella o vista restituisce un set risultato "live" se la query 
non contiene: 

• Una clausola DISTINCT nell'istruzione SELECT 

• Funzioni aggregate, con o senza clausole GROUP BY o HAVING 

• Riferimenti a piu tabelle base o viste aggiornabili (concatenamenti) 

• Subquery che fanno riferimento alia tabella nella clausola FROM o altre tabelle 

Se un'applicazione richiede e riceve un set risultato "live", la proprieta CanModify del 
componente query e impostata a true. La query, anche se restituisce un set risultato 
"live", potrebbe non essere in grado di aggiornare direttamente il set risultato nel 
caso contenesse campi collegati o se si commutassero gli indici prima di tentare 
l'aggiornamento. In presenza di queste condizioni, il set risultato andrebbe trattato 
come se fosse a sola lettura e andrebbe aggiornato di conseguenza. 

Se un'applicazione richiede un set risultato "live", ma la sintassi dell'istruzione 
SELECT non lo consente, BDE restituisce 

• Un set risultato a sola lettura nel caso di query rivolte a Paradox o a dBASE. 

• Un codice di errore nel caso di query SQL rivolte a un server remoto. 

Aggiornamento di set risultato a sola lettura 

Le applicazioni possono aggiornare dati restituiti in un set risultato a sola lettura se 
utilizzano gli aggiornamenti in cache. 

Se per gli aggiornamenti in cache si utilizza un dataset client, questo, o il provider 
associato puo generare automaticamente lo SQL per effettuare gli aggiornamenti, a 
meno che la query non rappresenti piu tabelle. In questo caso, e necessario indicare 
come applicare gli aggiornamenti: 

• Se tutti gli aggiornamenti sono applicati a una sola tabella di database, e possibile 
indicare alia tabella in questione l'aggiornamento tramite un gestore di evento 
OnGetTableName. 

• Se gli aggiornamenti vanno tenuti sotto stretto controllo, si puo associare la query 
a un oggetto update (TUpdateSQL). Un provider utilizza automaticamente questo 
oggetto update per applicare gli aggiornamenti: 

1 Associare l'oggetto update alia query, applicando la proprieta UpdateObject 
della query all'oggetto TUpdateSQL che si utilizza. 

2 Impostare le proprieta ModifySQL, InsertSQL e DeleteSQL dell'oggetto update a 
istruzioni SQL che eseguono gli opportuni aggiornamenti dei dati della query. 

Se si utilizza BDE per gli aggiornamenti in cache, e necessario utilizzare un oggetto 
update. 
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Per ulteriori informazioni sull'utilizzo di oggetti update, consultare "Aggiornamento 
di dataset mediante oggetti update" a pagina 24-41. 

Utilizzo di TStoredProc 



TStoredProc rappresenta una procedura registrata e implementa tutte le funzionalita 
di base introdotte da TDataSet, in aggiunta alia maggior parte delle funzioni speciali 
tipiche dei dataset di tipo procedura registrata. Prima di studiare le funzioni 
esclusive introdotte da TStoredProc, e bene impadronirsi delle funzionalita database 
comuni descritte in "I dataset",, compresa la sezione sui dataset di tipo procedura 
registrata che inizia a pagina pagina 22-52. 

TStoredProc e un dataset per BDE, per cui va associato a un database e a una sessione. 
II paragrafo "Associazione di un dataset a connessioni di database e di sessione" a 
pagina 24-3 spiega come formare queste associazioni. Una volta associato il dataset e 
a un database e a una sessione, e possibile collegarlo a una particolare procedura 
registrata impostando la proprieta StoredProcName. 

TStoredProc differisce dagli altri dataset di tipo procedura registrata per queste 
ragioni: 

• Consente di controllare meglio la connessione dei parametri. 

• Supporta le procedure registrate ridefinite Oracle. 

Inglobamento dei parametri 

Quando una procedura registrata viene preparata ed eseguita, i relativi parametri di 
input sono collegati automaticamente a parametri sul server. 

TStoredProc consente di usare la proprieta ParamBindMode per specificare in che 
modo collegare i parametri ai parametri sul server. Per impostazione predefinita 
ParamBindMode e impostato a pbByName, cioe i parametri provenienti dal 
componente procedura registrata corrispondono per nome a del server. Questo e il 
metodo piu facile di collegare i parametri. 

Determinati server supportano anche i parametri di connessione secondo il valore 
ordinale, cioe secondo l'ordine in cui i parametri vengono visualizzati nella 
procedura registrata. In questo caso, e significativo l'ordine in cui si specificano i 
parametri nell'editor di raccolta dei parametri. II primo parametro specificato 
corrisponde al primo parametro di input sul server, il secondo parametro al secondo 
parametro di input sul server, e cosi via. Se il server supporta la connessione di 
parametri secondo il valore ordinale, si puo impostare ParamBindMode a 
pbByNumber. 

Se si desidera impostare ParamBindMode a pbByNumber, e necessario specificare i tipi 
di parametro corretti nell'ordine corretto. Nello SQL Explorer si puo visualizzare il 
codice sorgente di una procedura registrata di un server per determinare l'ordine 
corretto e il tipo di parametri da specificare. 
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Operazioni con procedure registrate ridefinite di Oracle 

I server Oracle consentono la ridefinizionedelle procedure registrate; le procedure 
ridefinite sono procedure diverse che hanno lo stesso nome. La proprieta Overload del 
componente procedura registrata permette a un'applicazione di specificare quale 
procedura eseguire. 

Se Overload e zero (l'impostazione predefinita), si presume che non vi sia nessuna 
ridefinizione. Se Overload e uno (1), il componente procedura registrata esegue la 
prima procedura registrata che trova sul server Oracle contenente il nome ridefinito; 
se e due (2), esegue la seconda, e cosi via. 

Le procedure registrate ridefinite accettano parametri di input e di output diversi. 
Per ulteriori informazioni, fare riferimento alia documentazione del server Oracle. 

Collegamento ai database tramite TDatabase 



Quando un'applicazione C++Builder utilizza Borland Database Engine (BDE) per 
collegarsi a un database, la connessione e incorporata in un componente TDatabase. 
Un componente database rappresenta la connessione a un singolo database, nel 
contesto di una sessione BDE. 

TDatabase esegue molte delle attivita di altri componenti di connessione ai database 
con i quali ha in comune molte proprieta , metodi ed eventi. Proprieta , metodi ed 
eventi comuni sono spiegati nel Capitolo 21, "Connessione ai database.". 

In aggiunta a questo, TDatabase introduce molte funzioni specifiche di BDE, che 
vengono descritte qui di seguito. 

Associazione di un componente database a una sessione 

Tutti i componenti database devono essere associati a una sessione BDE. Per stabilire 
l'associazione si ricorre a SessionName. Quando si crea un componente database in 
fase di progetto, SessionName e impostato a "Default", il che significa che e associato 
al componente session predefinito che e referenziato dalla variabile globale Session. 

Le applicazioni multithread o reentrant BDE possono richiedere piu di una sessione. 
Se e necessario utilizzare sessioni multiple, bisogna aggiungere componenti TSession 
per ciascuna sessione. Poi si associata il dataset a un componente session impostando 
la proprieta SessionName alia proprieta SessionName di un componente session. 

In esecuzione, si accede al componente session cui il database e associato leggendo la 
proprieta Session. Se SessionName e vuoto o ha il valore "Default", allora la proprieta 
Session fa riferimento alia stessa istanza TSession referenziata dalla variabile globale 
Session. Session consente alle applicazioni di accedere alle proprieta , ai metodi e agli 
eventi del componente session superiore di un componente database senza conoscere 
il nome effettivo della sessione. 

Per ulteriori informazioni sulle sessioni BDE, vedere "Gestione delle sessioni di 
database" a pagina 24-17. 

Se si utilizza un componente database implicito, la sessione relativa per quel 
componente database e quella specificata dalla proprieta SessionName del dataset. 
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Interazioni tra il componente Session e i database 

Di solito, le proprieta del componente session determinano i comportamenti globali e 
predefiniti applicati a tutti i componenti database impliciti creati in fase di 
esecuzione. Ad esempio, la proprieta Keef Connections della sessione controllante 
determina se la connessione con un database rimane attiva anche quando sono chiusi 
i dataset associati (impostazione predefinita), o se i collegamenti vengono interrotti 
quando tutti i suoi dataset sono chiusi. Similmente, l'evento predefinito OnPassword 
di una sessione garantisce che quando un'applicazione tenta di collegarsi a un 
database su un server che richiede una password, appare una finestra di dialogo 
standard con la richiesta di indicare la password. 

L'applicazione dei metodi della sessione e piuttosto diversa. I metodi di TSession 
influiscono su tutti i componenti database, sia che vengano creati esplicitamente 
oppure istanziati implicitamente da un dataset. Ad esempio, il metodo di sessione 
Dr of Connections chiude tutti i dataset che appartengono ai componenti database di 
una sessione, poi interrompe tutti i collegamenti con il database, anche se la proprieta 
KeepConnection per singoli componenti database e true. 

I metodi dei componenti database si applicano solo ai dataset associati a un 
determinate componente database. Ad esempio, si supponga che il componente 
database Databasel sia associato alia sessione predefinita. Databasel->CloseDataSets() 
chiude solo i dataset associati a Databasel. I dataset aperti appartenenti ad altri 
componenti database all'interno della sessione predefinita rimarranno aperti. 

Identificazione del database 

AliasName e DriverName sono proprieta reciprocamente esclusive che identificano il 
server di database cui si collega il componente TDatabase. 

• AliasName specifica il nome di un alias BDE esistente da usare con il componente 
database. L'alias appare in liste a discesa successive dei componenti dataset 
consentendo la connessione al componente database desiderato. Se si specifica 
AliasName di un componente database, l'eventuale valore assegnato a DriverName 
viene cancellato perche il nome del driver fa sempre parte di un alias BDE. 

Gli alias BDE si creano e si modificano con Database Explorer o con il programma 
di utilita BDE Administration. Per ulteriori informazioni sulla creazione e la 
manutenzione degli alias BDE, consultare la relativa documentazione in linea. 

• DriverName e il nome di un driver BDE. Un nome di driver e un parametro in un 
alias BDE , ma si puo specificare il nome del driver invece dell'alias quando si crea 
l'alias locale BDE di un componente database utilizzando la proprieta 
DatabaseName. Specificando DriverName, l'eventuale valore precedentemente 
assegnato ad AliasName viene cancellato per evitare potenziali conflitti tra il nome 
del driver che si specifica e quello che fa parte dell'alias BDE identificato in 
AliasName. 

DatabaseName consente di fornire il nome di una connessione a un database. II nome 
fornito si aggiunge ad AliasName o a DriverName ed e locale all'applicazione. 
DatabaseName puo essere un alias BDE, o, nel caso di file Paradox e dBASE, il nome 
completo del percorso. Come AliasName, DatabaseName viene visualizzato in liste a 
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discesa di componenti dataset in modo da consentire la connessione ai componenti 
database. 

In progettazione, per specificare un alias BDE, si assegna un driver BDE o si crea un 
alias locale BDE, facendo doppio clic su un componente database e richiamando cosi 
Database Properties editor. 

E possibile immettere un DatabaseName nella casella di modifica Name nell'editor 
delle proprieta . Si puo immettere un nome di alias BDE esistente nella casella 
combinata nome Alias della proprieta Alias oppure selezionare tra gli alias esistenti 
nella lista a discesa. La casella combinata Driver name permette di immettere il nome 
di un driver BDE esistente per la proprieta DriverName, o altrimenti di scegliere tra i 
nomi dei driver esistenti nella lista a discesa. 

L'editor Database Properties permette anche di visualizzare e di impostare i 
parametri di connessione BDE e di impostare gli stati delle proprieta LoginPrompt e 
KeepConnection. Per informazioni sui parametri di connessione, consultare 
"Impostazione dei parametri degli alias BDE" qui di seguito. Per informazioni su 
LoginPrompt, consultare "Controllo del login al server" a pagina 21-4. Per 
informazioni su KeepConnection consultare "Apertura di una connessione utilizzando 
TDatabase" a pagina 24-16. 

Impostazione dei parametri degli alias BDE 

In progettazione e possibile creare o modificare i parametri di connessione in tre 
modi: 

• Utilizzare il programma di utilita Database Explorer o BDE Administration per 
creare o modificare alias BDE, tra cui i parametri. Per ulteriori informazioni su 
questi programmi di utilita , consultare i relativi file della Guida in linea. 

• Richiamare l'editor String List facendo doppio clic sulla proprieta Params 
nell'Object Inspector. 

• Richiamare l'editor Database Properties facendo doppio clic su un componente 
database in un modulo dati o in una scheda. 

Con tutti questi metodi si puo modificare la proprieta Params del componente 
database. Params e una lista di stringhe che contiene i parametri di connessione al 
database relativi all'alias BDE associato a un componente database. Alcuni parametri 
di connessione tipici comprendono percorso, nome server, dimensione della cache di 
schema, driver di linguaggio e modalita della query SQL. 

Quando si richiama il Database Properties editor, i parametri dell'alias BDE non sono 
visibili. Per vedere le impostazioni attive, fare clic su Defaults. I parametri attivi 
vengono visualizzati nel riquadro di nota Parameter overrides. E possibile 
modificare le voci esistenti o aggiungerne di nuove. Per cancellare i parametri 
esistenti, fare clic su Clear. Le modifiche apportate agiscono quando si fa clic su OK. 

In fase di esecuzione, un'applicazione puo impostare i parametri alias solo 
modificando direttamente la proprieta Params. Per ulteriori informazioni su 
parametri specifici per l'impiego dei di driver SQL Links con BDE, consultare il file 
della guida in linea SQL Links. 
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Apertura di una connessione utilizzando TDatabase 

Come avviene per tutti i componenti di connessione ai database, per collegarsi a un 
database mediante TDatabase si imposta la proprieta Connected a true o si chiama il 
metodo Open. La procedura e descritta in "Connessione a un server di database" a 
pagina 21-3. Una connessione, una volta che e stabilita, rimane attiva fino a quando 
almeno un dataset e attivo. Quando non ci sono piu dataset attivi, la connessione 
viene interrotta, a meno che non sia true la proprieta KeepConnection del componente 
database. 

Quando da un'applicazione ci si collega a un server di database remoto, 
l'applicazione stabilisce la connessione tramite BDE e il driver Borland SQL Links. 
(BDE pud anche comunicare con un driver ODBC che bisogna fornire). Prima di 
stabilire la connessione bisogna configurare il driver SQL Links o ODBC 
dell'applicazione. I parametri SQL Links e ODBC sono memorizzati nella proprieta 
Params del componente database. Per informazioni su parametri SQL Links, 
consultare SQL Links User's Guide. Per modificare la proprieta Params, consultare 
"Impostazione dei parametri degli alias BDE" a pagina 24-15. 

Operazioni con i protocolli di rete 

Per configurare il driver SQL Links o ODBC appropriato, puo essere necessario 
specificare il protocollo di rete utilizzato dal server, come SPX/IPX o TCP/IP, a 
seconda delle opzioni di configurazione del driver. Nella maggior parte dei casi, la 
configurazione del protocollo di rete si gestisce tramite il software di installazione 
client del server. Nel caso di ODBC potrebbe anche essere necessario controllare 
l'installazione del driver tramite il driver manager di ODBC. 

Stabilire il collegamento tra client e server a volte e problematico. La seguente lista 
delle anomalie di funzionamento si rivela utile se si incontrano difficolta : 

• La connessione dal lato client del server e configurata correttamente? 

• I DLL dei driver di connessione e di database si trovano nel percorso di ricerca? 

• Se si utilizza TCP/IP: 

• II software di comunicazione TCP/IP e stato installato? E stato installato il 
WINSOCK.DLL corretto? 

• L'indirizzo IP del server e registrato nel file HOSTS del client? 

• II Domain Name Services (DNS) e configurato correttamente? 

• E possibile eseguire il ping sul server? 

Per maggiori informazioni sulla ricerca delle anomalie, consultare SQL Links User's 
Guide e la documentazione del server. 

Uso di ODBC 

Un'applicazione puo utilizzare delle sorgenti dati ODBC (ad esempio, Btrieve). Una 
connessione tramite un driver ODBC richiede 

• Un driver ODBC acquistabile separatamente. 

• II Microsoft ODBC Driver Manager. 
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• II programma di utilita BDE Administration. 

Per configurare un alias BDE di una connessione driver ODBC, si utilizza il 
programma di utilita BDE Administration. Per ulteriori informazioni, consultare la 
guida in linea del programma di utilita BDE Administration. 

Impiego di componenti database nei moduli dati 

I componenti database si inseriscono in tutta sicurezza nei moduli dati. Tuttavia, se si 
mette nell'Object Repository un modulo dati contenente un componente database e si 
desidera che altri utenti siano in grado di ereditare da esso, e necessario impostare a 
true la proprieta HandleShared del componente database per evitare conflitti di spazio 
di nome globali. 

Gestione delle sessioni di database 



Le connessioni di database di un'applicazione BDE, i driver, i cursori, le query, e cosi 
via sono gestite all'interno del contesto di una o piu sessioni BDE. Le sessioni isolano 
un gruppo di operazioni di accesso al database, come i collegamenti, senza la 
necessita di avviare un'altra istanza dell'applicazione. 

Tutte le applicazioni database BDE includono automaticamente un componente 
session predefinito, chiamato Session, che comprende la sessione BDE predefinita. I 
componenti database aggiunti all'applicazione vengono associati automaticamente 
alia sessione predefinita (osservare che il suo SessionName e "Default"). La sessione 
predefinita fornisce il controllo totale di tutti i componenti database non associati a 
un'altra sessione, sia che siano impliciti (creati dalla sessione in esecuzione 
all'apertura di un dataset non associato a un componente database creato) o stabili 
(creati esplicitamente dall'applicazione). In fase di progetto, la sessione predefinita 
non e visibile nei modulo dati o nella scheda, ma in fase di esecuzione e possibile 
accedere alle sue proprieta e ai suoi metodi nei codice. 

Per utilizzare la sessione predefinita, non si deve scrivere alcun codice, a meno che 
l'applicazione non debba 

• Attivare esplicitamente o disattivare una sessione, attivando o disattivando la 
capacita di aprirsi dei database della sessione. 

• Modificare le proprieta della sessione, come la specifica delle proprieta predefinite 
dei componenti database generati implicitamente. 

• Eseguire i metodi di una sessione, come la gestione dei collegamenti al database 
(ad esempio aprendo e chiudendo la connessione in risposta ad azioni dell'utente). 

• Rispondere a eventi di sessione, come avviene quando l'applicazione tenta di 
accedere a una tabella Paradox o dBASE protetta da password. 

• Indicare la directory secondo le specifiche Paradox, come la proprieta NetFileDir 
per accedere a tabelle Paradox in rete e la proprieta PrivateDir sullo hard disk 
locale per per migliorare le prestazioni. 

• Gestire gli alias BDE che descrivono possibili configurazioni di connessione al 
database, relativamente a database e a dataset che utilizzano la sessione. 
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Sia che si aggiungano componenti database a un'applicazione in fase di 
progettazione, sia che si creino dinamicamente in fase di esecuzione, essi vengono 
associati automaticamente alia sessione predefinita, a meno che non li si assegni 
specificatamente a una sessione diversa. Se si apre un dataset non associato a un 
componente database, Delphi automaticamente 

• Crea per esso un componente database in fase di esecuzione. 

• Associa il componente database alia sessione predefinita. 

• Inizializza alcune proprieta chiave del componente database in base alle proprieta 
della sessione predefinita. Una delle piu importanti e KeepConnections, che 
determina quando un'applicazione deve mantenere attivo o chiudere i 
collegamenti. 

La sessione predefinita fornisce un insieme ampiamente applicabile di impostazioni 
predefinite utilizzabili cosi come sono nella maggior parte delle applicazioni. E 
necessario solo associare un componente database a una sessione esplicitamente 
chiamata, se il componente esegue una query simultanea verso un database gia 
aperto dalla sessione predefinita. In questo caso, ogni query simultanea va eseguita 
in una propria sessione. Anche le applicazioni database multithread richiedono 
sessioni multiple, in cui ogni thread ha la propria sessione. 

Le applicazioni possono creare ulteriori componenti session in base alle necessita . Le 
applicazioni database BDE includono automaticamente un componente session list, 
chiamato Sessions, utilizzabile per gestire tutti i componenti session. Per ulteriori 
informazioni sulla gestione di sessioni multiple, consultare "Gestione di sessioni 
multiple" a pagina 24-29. 

I componenti session si possono mettere senza problemi anche nei moduli dati. Se si 
mette un modulo dati che contiene uno o piu componenti session nell'Object 
Repository, tuttavia, bisogna assicurarsi che la proprieta AutoSessionName sia true 
per evitare conflitti di nome quando gli utenti ereditano da esso. 

Attivazione di una sessione 

Active e una proprieta Boolean che determina se il database e i componenti dataset 
associati a una sessione sono aperti. La proprieta puo servire per leggere lo stato 
corrente delle connessioni del database e del dataset di una sessione o per 
modificarlo. Se Active e false (l'impostazione predefinita), tutti i database e tutti i 
dataset associati alia sessione sono chiusi. Se e true, database e dataset sono aperti. 

Una sessione viene attivata quando la si crea e, successivamente, ogni volta che la sua 
proprieta Active viene modificata a true da false (ad esempio, quando un database o 
un dataset e associato con una sessione aperta e non ci sono altri database o dataset 
aperti). Impostando Active a true si innesca l'evento OnStartup della sessione, si 
registrano le posizioni di directory Paradox con BDE e si registra la proprieta 
ConfigMode, che determina quali alias BDE sono disponibili all'interno della sessione. 
E possibile scrivere un gestore di evento OnStartup per inizializzare le proprieta 
NetFileDir, PrivateDir e ConfigMode prima che esse siano registrate con BDE, o per 
eseguire altre specifiche attivita di avvio. Per informazioni sulle proprieta NetFileDir 
e PrivateDir, consultare "Specifica delle ubicazioni delle directory di Paradox" a 
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pagina 24-25. Per informazioni su ConfigMode, consultare "Operazioni con gli alias 
BDE" a pagina 24-25. 

Una volta attivata la sessione, e possibile aprire le sue connessioni con il database 
chiamando il metodo OpenDatabase. 

Nel caso di componenti session inseriti in un modulo dati o in una scheda, 
impostando Active a false si chiudono i database o i dataset aperti. In fase di 
esecuzione, la chiusura dei database e dei dataset attiva gli eventi associati. 

In fase di progettazione, non e consentito impostare Active a false per la sessione 
predefinita. Sebbene sia possibile chiudere la sessione predefinita in fase di 
esecuzione, e sconsigliabile farlo. 

In fase di esecuzione, si possono anche utilizzare i metodi Open e Close di una 
sessione per attivare o disattivare sessioni diverse dalla sessione predefinita. Ad 
esempio, con quest'unica riga di codice si chiudono tutti i database e i dataset aperti 
di una sessione: 

Sessionl->Close() ; 

Questo codice imposta la proprieta Active di Sessioni a false. Quando la proprieta 
Active di una sessione e false, un ulteriore tentativo dell'applicazione di aprire un 
database o un dataset reimposta Active a true e chiama il gestore di evento OnStartup 
della sessione, se esiste. E possibile anche codificare esplicitamente la riattivazione 
della in fase di esecuzione. II seguente codice riattiva Sessioni: 

Sessionl->Open() ; 

Quando una sessione e attiva si possono aprire e chiudere i singoli collegamenti al 
database. Per ulteriori informazioni, consultare "Chiusura delle connessioni con il 
database" a pagina 24-20. 



Specifica del comportamento predefinito della connessione al database 

KeepConnections fornisce il valore predefinito della proprieta KeepConnection dei 
componenti database impliciti creati in fase di esecuzione. KeepConnection specifica 
che cosa accade a una connessione di database stabilita per un componente database 
quando tutti i suoi dataset sono chiusi. Se e true (l'impostazione predefinita), si 
stabilisce una connessione costante o stabile anche se non ci sono dataset attivi. 
Quando e false, la connessione viene interrotta non appena tutti i suoi dataset sono 
chiusi. 

La persistenza della connessione di un componente database inserito esplicitamente 
in un modulo dati o in una scheda e controllata dalla sua proprieta KeepConnection. Se 
impostata diversamente, KeepConnection del componente database prevale sempre 
sulla proprieta KeepConnections della sessione. Per ulteriori informazioni sul controllo 
delle singole connessioni database all'intemo di una sessione, consultare "Gestione 
delle connessioni con il database" a pagina 24-20. 

KeepConnections dovrebbe essere impostato a true nelle applicazioni che aprono e 
chiudono frequentemente tutti i dataset associati a un database situato su un server 
remoto. Questa impostazione riduce il traffico di rete e velocizza l'accesso ai dati, in 
quanto significa che nel corso della sessione la connessione viene aperta e chiusa solo 
una volta. Altrimenti, l'applicazione ogni volta che chiude o ristabilisce la 
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connessione, deve affrontare l'incombenza aggiuntiva della connessione o dello 
scollegamento con il database. 

Anche quando in una sessione KeepConnections e true, chiamando il metodo 
D? 'op 'Connections e possibile chiudere e liberare i collegamenti database non attivi 
relativamente a tutti i componenti database impliciti. Per ulteriori informazioni su 
Drop 'Connections , consultare "Rilascio delle connessioni database non attive" a 
pagina 24-21. 

Gestione delle connessioni con il database 

E possibile utilizzare un componente session per gestire i collegamenti con un 
database. II componente session contiene le proprieta e i metodi che utilizzabili per 

• Aprire i collegamenti con il database. 

• Chiudere i collegamenti con il database. 

• Chiudere e disimpegnare tutti i collegamenti con il database non attivi. 

• Individuare collegamenti specifici con il database. 

• Iterare attraverso tutte le connessioni con il database aperte. 

Apertura delle connessioni con il database 

Per aprire una connessione database all'interno di una sessione, si chiama il metodo 
OpenDatabase. OpenDatabase accetta un parametro, il nome del database da aprire. II 
nome e un alias BDE, oppure il nome di un componente database. Nel caso di 
Paradox o di dBASE, il nome pud anche essere il nome del percorso per esteso. Ad 
esempio, la seguente istruzione utilizza la sessione predefinita e tenta di stabilire la 
connessione con il database puntato dall'alias BCDEMOS: 

TDatabase *BCDemosDatabase = Session->OpenDatabase ("BCDEMOS 11 ) ; 

OpenDatabase attiva la sessione se questa non e gia attiva e poi verifica se il nome del 
database specificato corrisponde alia proprieta DatabaseName di qualsiasi 
componente database della sessione. Se il nome non corrisponde a un componente 
database esistente, OpenDatabase ne crea uno temporaneo utilizzando il nome 
specificato. Infine, OpenDatabase chiama il metodo Open del componente database 
per la connessione al server. Ogni chiamata a OpenDatabase fa aumentare di un'unita 
il numero di riferimento del database. II database rimane aperto fino a quando il 
numero di riferimento e maggiore di 0. 

Chiusura delle connessioni con il database 

Per chiudere una singolo collegamento con un database, si chiama il metodo 
CloseDatabase. Quando si chiama CloseDatabase, il numero di riferimento del database, 
che viene incrementato ogni volta che si chiama OpenDatabase, diminuisce di 
un'unita . Quando il numero di riferimento e 0, il database viene chiuso. 
CloseDatabase accetta un parametro, il database da chiudere. Se il database e stato 
aperto utilizzando il metodo OpenDatabase, questo parametro puo essere impostato al 
valore restituito da OpenDatabase. 

Session->CloseDatabase(BCDemosDatabase) ; 
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Se il nome del database specificato e associato a un componente database 
temporaneo (implicito) e la proprieta KeepConnections della sessione e false, il 
componente database viene liberato, e la connessione viene effettivamente chiusa. 

Se KeepConnections e false i componenti database temporanei vengono chiusi e 
liberati automaticamente quando si chiude l'ultimo dataset associato al componente 
database. Un'applicazione puo sempre chiamare CloseDatabase in anticipo per forzare 
la chiusura. Per liberare dei componenti database temporanei quando 
KeepConnections e true, si chiamano il metodo Close del componente database, e poi il 
metodo DropConnections della sessione. 

La chiamata di CloseDatabase per un componente database costante in realta non 
chiude la connessione. Alio scopo, bisogna chiamare direttamente il metodo Close del 
componente database. 

Ci sono due modi per chiudere tutte le connessioni database all'interno della 
sessione: 

• Impostare la proprieta Active della sessione a false. 

• Chiamare il metodo Close della sessione. 

Quando Active ha il valore false, C++Builder chiama automaticamente il metodo 
Close. Close si scollega da tutti i database attivi, liberando i componenti database 
temporanei e chiamando ogni metodo Close del componente database stabile. Infine, 
Close assegna il valore NULL al gestore BDE della sessione. 

Rilascio delle connessioni database non attive 

Se la proprieta KeepConnections di una sessione e true (l'impostazione predefinita), 
allora le connessioni database dei componenti database temporanei rimangono attive 
anche se sono chiusi tutti i dataset utilizzati dal componente. E possibile eliminare i 
collegamenti in questione e liberare tutti i componenti database temporanei non 
attivi di una sessione chiamando il metodo DropConnections. Ad esempio, il seguente 
codice libera tutti i componenti database non attivi e temporanei della sessione 
predefinita: 

Session->DropConnections ( ) ; 

I componenti database temporanei che hanno uno o piu dataset attivi non vengono 
rilasciati o liberato da questa chiamata. Per liberare questi componenti, chiamare 
Close. 

Ricerca di una connessione con un database 

Per determinare se un componente database specificato e gia associato a una sessione 
si utilizza il il metodo FindDatabase. FindDatabase accetta un parametro, il nome del 
database da cercare, che puo essere l'alias BDE o il nome del componente database. 
Per Paradox o per dBASE, puo anche essere il nome del percorso per esteso. 

FindDatabase restituisce il componente database se trova una corrispondenza. 
Altrimenti restituisce NULL. 

II seguente codice cerca nella sessione predefinita un componente database 
utilizzando l'alias BCDEMOS e, se non lo trova, ne crea uno e lo apre: 

TDatabase *DB = Session->FindDatabase ("BCDEMOS" ) ; 
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if ( ! DB ) // Database does not exist for session so 

DB = Session->OpenDatabase("BCDEMOS"); // create and open it 
if (DB && DB->Connected) 

{ 

if ( !DB->InTransaction) 

{ 

DB->StartTransaction() ; 

} 

} 

Iterazione tra i componenti database di una sessione 

E possibile utilizzare due proprieta del componente sessione, Databases e 
DatabaseCount, per iterare attraverso tutti i componenti database attivi associati a una 
sessione. 

Databases e un array di tutti i componenti database attivi associati a una sessione. 
DatabaseCount e il numero di database dell'array. Mano a mano che i collegamenti si 
aprono e si chiudono nel corso della sessione, i valori di Databases e di DatabaseCount 
cambiano. Ad esempio, se la proprieta Keep 'Connections una sessione e false e in fase 
di esecuzione tutti i componenti database vengono creati in base alle necessita , ogni 
volta che un certo database viene aperto, DatabaseCount viene aumentato di un'unita 
. Ogni volta che un certo database viene chiuso, DatabaseCount diminuisce da uno. Se 
DatabaseCount e zero, la sessione non contiene componenti database attivi. 

In questo esempio viene impostata a true la proprieta KeepConnection di ciascun 
database attivo nella sessione predefinita: 

if (Session->DatabaseCount > 0) 
for (int MaxDbCount = 0; MaxDbCount < Session->DatabaseCount; MaxDbCount++) 
Session->Databases [MaxDbCount] ->KeepConnection = true; 

Operazioni con ta belle Paradox e dBASE protette da password 

Un componente session puo memorizzare le password delle tabelle Paradox e 
dBASE protette da password. Una volta aggiunta una password alia sessione, 
l'applicazione in grado di aprire le tabelle che la password protegge. Quando si toglie 
la password dalla sessione, l'applicazione non puo aprire tabelle che utilizzano la 
password fino a quando questa non viene nuovamente aggiunta. 

Uso del metodo AddPassword 

II metodo AddPassword e un modo facoltativo perche un'applicazione fornisca una 
password per una sessione prima dell'apertura di una tabella crittografata Paradox o 
dBASE alia quale si puo accedere solo indicando la password. Se non si aggiunge la 
password alia sessione, una finestra di dialogo richiede una password all'utente 
quando l'applicazione tenta di aprire una tabella protetta da password. 

AddPassword accetta un parametro contenente la password da utilizzare, una stringa. 
E possibile chiamare AddPassword ogni qual volta e necessario per aggiungere (una 
alia volta) le password che consentono di accedere alle tabelle protette con varie 
password. 

AnsiString PassWrd; 
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PassWrd = InputBox( "Enter password", "Password:", ""); 

Session->AddPassword(PassWrd) ; 

try 

{ 

Tablel->Open() ; 

} 

catch (...) 

{ 

ShowMessage( "Could not open table!"); 
Application->Terrainate ( ) ; 

} 

L'utilizzo della funzione InputBox, sopra, ha solo scopi dimostrativi. Nelle 
applicazioni reali, si ricorre alle funzionalita di immissione della password che 
nascondono i singoli caratteri durante 1'immissione, come la funzione PasswordDialog 
o una scheda custom. 

II pulsante Add della finestra di dialogo di PasswordDialog agisce proprio come il 
metodo AddPassword. 

if (PasswordDlg (Session) ) 

Tablel->Open() ; 
else 

ShowMessageC'No password given, could not open table!"); 

Utilizzo dei metodi RemovePassword e RemoveAIIPasswords 

RemovePassword cancella dalla memoria una password precedentemente inserita. 
RemovePassword accetta un parametro contenente la password da cancellare. 

Session->RemovePassword ( "secret " ) ; 

RemoveAIIPasswords cancella dalla memoria tutte le password precedentemente 
aggiunte. 

Session->RemoveAllPasswords ( ) ; 

Utilizzo del metodo GetPassword e dell'evento OnPassword 

L'evento OnPassword permette di controllare in che modo l'applicazione fornisce le 
password quando vengono richieste quelle relative alle tabelle Paradox e dBASE. Se 
si desidera ridefinire il comportamento di gestione della password predefinita 
bisogna fornire il gestore dell'evento OnPassword. Quando non si fornisce il gestore, 
C++Builder presenta una finestra di dialogo predefinita per 1'immissione di una 
password ma non e previsto nessun comportamento particolare-o il tentativo di 
aprire la tabella riesce, oppure viene sollevata un'eccezione. 

Se si fornisce il gestore dell'evento OnPassword, questo deve fare due cose: chiamare 
il metodo AddPassword e impostare il parametro Continue del gestore di evento a true. 
II metodo AddPassword passa alia sessione una stringa da utilizzare come password 
della tabella. II parametro Continue indica a C++Builder che non sono necessarie 
ulteriori richieste di password per questo tentativo di aprire la tabella. II valore 
predefinito di Continue e false per cui bisogna dargli esplicitamente il valore true. Se 
Continue e false, terminata l'esecuzione del gestore di evento, riparte un evento 
OnPassword -anche se mediante AddPassword e stata passata la password valida. Se 
Continue e true, dopo l'esecuzione del gestore di evento e se la stringa passata con 
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AddPassword non e la password valida, il tentativo di aprire la tabella non riesce e 
viene sollevata un'eccezione. 

OnPassword puo essere innescato da due circostanze. II primo e il tentativo di aprire 
una tabella protetta da password (dBASE o Paradox) quando alia sessione non e stata 
gia fornita la password valida. (in caso contrario, l'evento OnPassword non si 
verifica). 

L'altra circostanza e una chiamata al metodo GetPassword. GetPassword genera un 
evento OnPassword oppure, se la sessione non ha un gestore di evento OnPassword, 
visualizza una finestra di dialogo Default password. Restituisce true se il gestore di 
evento OnPassword o la finestra di dialogo predefinita hanno aggiunto una password 
alia sessione, e false se non e stata indicata nessuna stringa. 

Nel seguente esempio, il metodo Password e indicato come gestore di evento 
OnPassword della sessione predefinita, assegnandolo alia proprieta OnPassword 
dell'oggetto globale Session. 

void __fastcall TForml: :FormCreate(TObject *Sender) 

{ 

Session->OnPassword = Password; 

} 

Nel metodo Password, la funzione InputBox chiede la password all'utente. II metodo 
AddPassword poi fornisce da programma alia sessione la password immessa nella 
finestra di dialogo. 

void __fastcall TForml: :Password(TObject *Sender, bool &Continue) 
{ 

AnsiString PassWrd = InputBox ("Enter password", "Password:", ""); 
Session->AddPassword(PassWrd) ; 
Continue = (PassWrd > ""); 

} 

L'evento OnPassword (e pertanto il gestore di evento Password) viene innescato da un 
tentativo di aprire una tabella protetta da password, come dimostrato qui di seguito. 
Sebbene il gestore di evento OnPassword chieda all'utente di fornire la password, il 
tentativo di aprire la tabella puo fallire nel caso si immetta una password non valida 
o se qualcos'altro non va a buon fine. 

void __fastcall TForml: :OpenTableBtnClick(TObject *Sender) 
{ 

try 

{ 

// this line triggers the OnPassword event 
Tablel->Open ( ) ; 

} 

// exception if cannot open table 
catch (...) 

{ 

ShowMessage( "Could not open table!"); 
Application->Terminate ( ) ; 

} 

} 
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Specifica delle ubicazioni delle directory di Paradox 

Due proprieta del componente sessione, NetFileDir e PrivateDir, riguardano 
specificamente le applicazioni che lavorano con tabelle Paradox. 

NetFileDir specifica la directory che contiene PDOXUSRS.NET, il file di controllo di 
rete di Paradox. Questo file governa la condivisione delle tabelle Paradox sulle unita 
di rete. Tutte le applicazioni che devono condividere delle tabelle Paradox devono 
specificare la stessa directory del file di controllo di rete (di solito una directory su un 
file server di rete). Per un certo alias di database, C++Builder deriva il valore per 
NetFileDir dal file di configurazione di Borland Database Engine (BDE). Se si imposta 
personalmente NetFileDir, il valore fornito prevale sull'impostazione di 
configurazione di BDE, per cui bisogna assicurarsi di convalidare il nuovo valore. 

In fase di progetto, si puo indicare il valore di NetFileDir tramite l'Object Inspector. Si 
puo anche impostare o modificare NetFileDir nel codice, in fase di esecuzione. II 
seguente codice impostare NetFileDir per la sessione predefinita all'ubicazione della 
directory da dove l'applicazione viene eseguita: 

Session->NetFileDir = ExtractFilePath(ParamStr(0) ) ; 

NetFileDir puo essere modificato solo quando in un'applicazione non ci sono file 
Paradox aperti. Se si modifica NetFileDir in esecuzione, bisogna verificare che esso 
punti una directory di rete valida che sia condivisa dagli utenti di rete. 

PrivateDir specifica la directory dove vengono registrati i i file temporanei di 
elaborazione delle tabelle, come quelli che BDE genera per gestire le istruzioni SQL 
locali. Se non viene specificato il valore della proprieta PrivateDir, BDE nel momento 
in cui viene inizializzato utilizza automaticamente la directory corrente. Se 
l'applicazione viene eseguita direttamente da un file server di rete, e possibile 
migliorare in esecuzione la performance dell'applicazione impostando PrivateDir su 
un disco rigido locale di un utente prima di aprire il database. 

Non impostare PrivateDir in fase di progettazione per poi aprire la sessione nell'IDE. 
Cosi facendo, viene generato l'errore Directory is busy quando l'applicazione viene 
eseguita a partire e dall'IDE. 

II seguente codice modifica l'impostazione della proprieta PrivateDir della sessione 
predefinita sulla directory C: \TEMP di un utente: 

Session->PrivateDir = "C: WTEMP" ; 

Non impostare PrivateDir sulla directory principale di un drive. Bisogna sempre 
specificare una subdirectory. 



Operazioni con gli alias BDE 

Ogni componente database associato a una sessione ha un alias BDE (benche il nome 
del percorso per esteso possa facoltativamente essere sostituito da un alias quando si 
accede a tabelle Paradox e dBASE). Una sessione quando e attiva puo creare, 
modificare e cancellare gli alias. 

II metodo AddAlias crea un nuovo alias BDE per un server di database SQL. AddAlias 
prende tre parametri: una stringa che contiene un nome per l'alias, una stringa che 
specifica il driver SQL Links da utilizzare e una stringa lista popolata di parametri 
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per l'alias. Ad esempio, le seguenti istruzioni utilizzano AddAlias per aggiungere un 
nuovo alias per l'accesso a un server InterBase alia sessione predefinita: 

TStringList *AliasParams = new TStringList () ; 
try 

{ 

AliasParams->Add("OPEN M0DE=READ" ) ; 
AliasParams->Add("USER NAME=TOMSTOPPARD" ) ; 
AliasParams->Add("SERVER NAME=ANIMALS : /CATS/PEDIGREE. GDB" ) ; 
Session->AddAlias("CATS", " INTRBASE " , AliasParams); 

} 

catch (...) 

{ 

delete AliasParams; 
throw; 

} 

delete AliasParams; 

AddStandard Alias crea un nuovo alias BDE per le tabelle Paradox, dBASE o ASCII. 
AddStandardAlias accetta tre parametri di stringa: il nome dell'alias, il percorso 
completo della tabella Paradox o dBASE cui si vuole accedere e il nome del driver 
predefinito driver da usare quando si cerca di aprire una tabella priva di estensione. 
Ad esempio, la seguente istruzione utilizza AddStandardAlias per creare un nuovo 
alias per accedere a una tabella Paradox: 

Session->AddStandardAlias("MYBCDEMOS", "C: WTESTINGWDEMOSW " , "Paradox") ; 

Quando si aggiunge un alias a una sessione, BDE registra una copia dell'alias in 
memoria, dove e disponibile per la sessione in corso e per le altre sessioni che 
includano il valore cfmPersistent nella proprieta ConfigMode. ConfigMode e un set che 
descrive quali tipi di alias possono essere utilizzati dai database della sessione. 
L'impostazione predefinita e cmAll, che equivale al set [ cfmVirtual, cfmPersistent, 
cfmSession ]. Se ConfigMode e cmAll, la sessione vede tutti gli alias creati al suo interno 
(cfmSession), tutti gli alias nel file di configurazione BDE sul sistema dell'utente 
(cfmPersistent) e tutti gli alias che BDE conserva in memoria (cfmVirtual). E possibile 
modificare ConfigMode per limitare quali alias BDE i database in una sessione 
possono utilizzare. Ad esempio, l'impostazione di ConfigMode a cfmSession fa vedere 
alia sessione solo gli alias creati all'interno della sessione. Tutti gli altri alias presenti 
nel file di configurazione BDE e in memoria non sono disponibili. 

Per mettere un alias appena creato a disposizione di tutte le sessioni e di altre 
applicazioni, si ricorre al metodo SaveConfigFile della sessione. SaveConfigFile scrive 
alias in memoria sul file di configurazione BDE, dove altre applicazioni BDE capaci 
di funzionare con BDE possono leggerli e utilizzarli. 

Dopo avere creato un alias, per modificarne i parametri si ricorre a Modify Alias. 
Modify Alias accetta due parametri: il nome dell'alias da modificare e una lista di 
stringhe contenente i parametri da cambiare e i rispettivi valori. Ad esempio, con le 
seguenti istruzioni ModifyAlias cambia in READ/WRITE il parametro OPEN MODE 
dell'alias CATS facendolo diventare nella sessione predefinita: 

TStringList *List = new TStringList () ; 
List->Clear() ; 

List->Add("OPEN MODE=READ/WRITE" ) ; 
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Session->ModifyAlias("CATS", List) ; 
delete List; 

Per cancellare un alias precedentemente creato nel corso di una sessione, si ricorre al 
metodo DeleteAlias. DeleteAlias accetta un parametro, il nome dell'alias da cancellare 
e rende inaccessibile l'alias alia sessione. 

DeleteAlias non rimuove un alias dal file di configurazione BDE se l'alias e stato 
scritto sul file da una chiamata precedente a SaveConfigFile. Per togliere l'alias dal file 
di configurazione dopo avere chiamato DeleteAlias, bisogna chiamare nuovamente 
SaveConfigFile. 

I componenti session forniscono cinque metodi per recuperare le informazioni 
relative a un alias BDE, comprese le informazioni sul parametro e quelle sul driver. 
Essi sono: 

• GetAliasNames, per elencare gli alias ai quali una sessione ha accesso. 

• GetAliasParams, per elencare i parametri di un alias specificate 

• GetAliasDriverName, per restituire il nome del driver BDE utilizzato dall'alias. 

• GetDriverNames, per restituire una lista di tutti i driver BDE disponibili per la 
sessione. 

• GetDriverParams, per restituire parametri di driver relativi a un driver specificate 

Per ulteriori informazioni sull'utilizzo dei metodi per recuperare le informazioni di 
una sessione, consultare "Reperimento di informazioni su una sessione" qui di 
seguito. Per ulteriori informazioni sugli alias BDE e sui driver SQL Links con cui essi 
funzionano, consultare la Guida BDE in linea, BDE32.HLP. 

Reperimento di informazioni su una sessione 

Per recuperare le informazioni su una sessione e sui suoi componenti database si 
utilizzano i metodi informativi di una sessione. Ad esempio, un metodo recupera i 
nomi di tutti gli alias conosciuti dalla sessione, e un altro recupera i nomi delle tabelle 
associate a uno specifico componente database utilizzato dalla sessione. La Tabella 
24.4 riassume i metodi informativi di un componente session: 

Tabella 24.4 Metodi informativi correlati al database dei componenti session 
Metodo Scopo 

GetAliasDriverName Recupera il driver BDE dell'alias specificato di un database. 
GetAliasNames Recupera la lista degli alias BDE di un database. 

GetAliasParams Recupera la lista di parametri dell'alias BDE specificato di un database. 

GetConfigParams Recupera informazioni di configurazione dal file di configurazione 
BDE. 

GetDatabaseNames Recupera la lista degli alias BDE e i nomi di tutti i componenti TDatabase 
attualmente in uso. 

GetDriverNames Recupera i nomi di tutti i driver BDE installati. 

GetDriverParams Recupera la lista di parametri di un driver BDE specificato. 

GetStoredProcNames Recupera i nomi di tutte le procedure registrate relative a un database 
specificato. 
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Tabella 24.4 Metodi informativi correlati al database dei componenti session (continua) 



Metodo 


Scopo 


GetTableNames 


Recupera i nomi di tutte le tabelle di un database specificato 




corrispondenti a una struttura specificata. 


GetFieldNames 


Recupera i nomi di tutti i campi di una tabella specificata in un database 




specificato. 



Salvo GetAliasDriverName, questi metodi restituiscono un set di valori in una lista di 
stringhe dichiarata e gestita dall'applicazione. (GetAliasDriverName restituisce una 
sola stringa, il nome del driver BDE attivo di un particolare componente database 
utilizzato dalla sessione). 

Ad esempio, il seguente codice ricerca i nomi di tutti i componenti database e gli alias 
conosciuti alia sessione predefinita: 

TStringList *List = new TStringList () ; 
try 

{ 

Session->GetDatabaseNames (List) ; 

} 

catch (...) 

{ 

delete List; 
throw ; 

} 

delete List; 



Creazione di sessioni supplementari 

E possibile creare sessioni per integrare la sessione predefinita. In fase di 
progettazione, si possono situare le sessioni supplementari su un modulo dati (o su 
una scheda), impostarne le proprieta nell'Object Inspector, scrivere per loro dei 
gestori di evento, oltre a scrivere il codice per chiamare i loro metodi. Anche in fase 
di esecuzione si possono creare sessioni, impostarne le proprieta e chiamarne i 
metodi. 

Creare sessioni supplementari e facoltativo, salvo il caso in cui l'applicazione esegua 
query simultanee in un database, oppure l'applicazione sia di tipo multithread. 

In fase di esecuzione per attivare la creazione dinamica di un componente session, 
seguire questi passi: 

1 Dichiarare una variabile TSession. 

2 Istanziare una nuova sessione usando l'operatore new.Questo operatore chiama il 
costruttore di TSession per creare e inizializzare una nuova sessione. II costruttore 
assegna alia sessione una lista vuota di componenti database, imposta a true la 
proprieta KeepConnections, e inserisce la sessione nella lista gestita dal componente 
session list dell'applicazione. 

3 Assegnare un nome univoco alia proprieta SessionName della nuova sessione a. 
Questa proprieta serve per per associare componenti database alia sessione. Per 
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ulteriori informazioni sulla proprieta SessionName, consultare "Attribuzione del 
nome a una sessione" a pagina 24-29. 

4 Attivare la sessione e facoltativamente modificarne le proprieta . 

E possibile anche creare e aprire sessioni tramite il metodo OpenSession di 
TSessionList. Usare OpenSession e piu sicuro che utilizzare l'operatore new, perche 
OpenSession crea una sessione solo se questa non esiste gia . Per informazioni su 
OpenSession, consultare "Gestione di sessioni multiple" a pagina 24-29. 

II seguente codice crea un nuovo componente session, gli assegna un nome e apre la 
sessione per svolgere delle operazioni su un database (qui non riportate). Dopo 
l'utilizzo, il componente viene distrutto mediante una chiamata al metodo Free. 

Non cancellare mai la sessione predefinita. 

TSession *SecondSession = new TSession (Forml) ; 
try 

{ 

SecondSession->SessionName = "SecondSession" ; 
SecondSession->KeepConnections = false; 
SecondSession->Open ( ) ; 

} 

finally 

{ 

delete SecondSession; 

}; 

Attribuzione del nome a una sessione 

La proprieta SessionName di una sessione serve per dare il nome alia sessione, in 
modo che sia possibile associarle i database e i dataset. Nel caso della sessione 
predefinita, SessionName vale "Default", For ogni componente session aggiuntivo che 
si crea, e necessario dare un valore univoco alia sua proprieta SessionName. 

I componenti database e dataset hanno proprieta SessionName che corrispondono alia 
proprieta SessionName di un componente session. Se si lascia vuota la proprieta 
SessionName di un componente database o dataset questa viene associata 
automaticamente alia sessione predefinita. E possibile anche assegnare a SessionName 
di un componente database o dataset un nome corrispondente al SessionName di un 
componente session che si crea. 

II seguente codice utilizza il metodo OpenSession del componente predefinito 
TSessionList, Sessions, per aprire un nuovo componente session, assegnare al suo 
SessionName il nome "InterBaseSession", attivare la sessione e associare alia sessione 
Databasel, un componente database esistente: 

TSession *IBSession = Sessions->OpenSession ( "InterBaseSession" ) ; 
Databasel->SessionName = "InterBaseSession"; 

Gestione di sessioni multiple 

Se si crea una singola applicazione che utilizza piu thread per svolgere operazioni sul 
database, e necessario creare una sessione supplementare per ogni thread. La pagina 
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BDE sulla Component palette contiene un componente session che in fase di 
progettazione si puo mettere in un modulo dati o su una scheda. 

Quando si colloca un componente session, e necessario anche dare alia sua proprieta 
SessionName un valore univoco, per evitare conflitti con la proprieta SessionName 
della sessione predefinita. 

II fatto di inserire in fase di progetto un componente session presuppone che il 
numero di thread (e quindi di sessioni) richiesti dall'applicazione durante 
l'esecuzione sia stabile. Tuttavia, e piu probabile che un'applicazione debba creare 
sessioni dinamicamente. Per creare delle sessioni in modo dinamico, bisogna 
chiamare in fase di esecuzione il metodo OpenSession dell'oggetto globale Sessions. 

OpenSession richiede un singolo parametro, un nome di sessione univoco rispetto a 
tutti i nomi di sessione dell'applicazione. Con questo codice si crea dinamicamente e 
si attiva una nuova sessione con un nome generato univocamente: 

Sessions->OpenSession("RunTimeSession" + IntToStr (Sessions->Count + 1)); 

Questa istruzione genera un nome univoco di una nuova sessione recuperando il 
numero di sessioni corrente e aggiungendo uno al valore trovato. Notare che se si 
creano e distruggono dinamicamente delle sessioni in fase di esecuzione, l'esempio 
qui riportato non si comporta come previsto. Tuttavia, l'esempio mostra come 
utilizzare le proprieta e i metodi di Sessions per gestire sessioni multiple. 

Sessions e una variabile di tipo TSessionList che viene automaticamente istanziata nel 
caso di applicazioni database BDE. Le proprieta e i metodi di Sessions si utilizzano 
per tenere il conto di sessioni multiple nelle applicazioni database multithread. La 
Tabella 24.5 riassume le proprieta e i metodi del componente TSessionList: 

Tabella 24.5 Proprieta e metodi di TSessionList 
Proprieta o metodo Scopo 

Count Restituisce il numero di sessioni, sia attive che non attive, presenti nella 

lista di sessioni. 

FindSession Cerca la sessione con il nome specificato e restituisce un puntatore ad essa, 

oppure restituisce NULL se la con il nome specificato non esiste. Se viene 
passato un nome di sessione vuoto, FindSession restituisce un puntatore 
alia sessione predefinita, Session. 

GetSessionNames Mette in una lista di stringhe i nomi di tutti i componenti session correnti. 

La procedura aggiunge sempre almeno una stringa, "Default", per la 
sessione predefinita. 

List Restituisce il componente session di un nome di sessione specificato. Se 

non c'e alcuna sessione con il nome specificato, viene sollevata 
un'eccezione. 

OpenSession Crea e attiva una nuova sessione oppure riattiva una sessione esistente 

relativamente a un nome di sessione specificato. 

Sessions Accede alia lista di sessioni in base al valore ordinale. 



Come esempio dell'uso delle proprieta e dei metodi Sessions in un'applicazione 
multithread, si consideri che cosa accade quando si intende aprire una connessione 
con un database. Per stabilire se la connessione e gia in corso, si ricorre alia proprieta 
Sessions per far passare ciascuna sessione presente nella lista sessioni a partire dalla 
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sessione predefinita. Per ciascun componente session, si esamina la proprieta 
Databases per vedere se il database in questione e aperto. Se si scopre che un altro 
thread sta gia usando il database richiesto, si esamina la sessione successiva nella 
lista. 

Se un thread esistente non utilizza il database, allora si puo stabilire la connessione 
all'interno di quella sessione. 

Se, d'altra parte, tutti i thread esistenti utilizzano il database, e necessario aprire una 
nuova sessione in cui aprire un'altro collegamento con il database. 

Se in un'applicazione multithread si replica un modulo dati contenente una sessione, 
e ogni thread contiene una propria copia del modulo dati, con la proprieta 
AutoSessionName ci si puo accertare che tutti i dataset del modulo dati utilizzino la 
sessione corretta. L'impostazione di AutoSessionName a true fa in modo che la 
sessione quando viene creata in fase di esecuzione generi dinamicamente il proprio 
nome univoco. II nome poi viene assegnato a ciascun dataset del modulo dati, 
ridefinendo qualunque nome di sessione esplicitamente impostato. In questo modo si 
ha la certezza che ciascun thread abbia la propria sessione e che ciascun dataset 
utilizzi la sessione nel proprio modulo dati. 

Utilizzo delle transazioni con BDE 



Per impostazione predefinita, BDE fornisce un controllo di transazione implicito alle 
applicazioni. Quando un'applicazione e soggetta a controllo di transazione implicito, 
per ciascun record di un dataset che viene scritto nel database sottostante si ricorre a 
una transazione separata. Le transazioni implicite garantiscono il minimo di conflitti 
di aggiornamento di record sia una vista coerente del database. D'altra parte, siccome 
per ogni riga di dati scritti in un database si ricorre a una transazionedistinta, il 
controllo di transazione implicito puo portare a un eccessivo traffico di rete e a un 
rallentamento delle prestazioni. Inoltre II controllo di transazione implicito non 
protegge le operazioni logiche che impegnano piu di un record. 

Se si controllano esplicitamente le transazioni, si puo scegliere il momento migliore 
per per farle partire, impegnarle e per fare il rollback. Nello sviluppo di applicazioni 
in ambiente multiutente, in particolare quando le applicazioni vengono eseguite su 
un server SQL remoto, si dovrebbero controllare le transazioni esplicitamente. 

Nelle applicazioni database basate su BDE ci sono due modi che si escludono 
reciprocamente per il controllo esplicito delle transazioni 

• II controllo viene fatto mediante il componente database. II vantaggio principale 
dell'impiego dei metodi e delle proprieta di un componente database e quello di 
fornire un'applicazione pulita e portabile, indiprendente dal database o dal server. 
Questo tipo di controllo di transazione e supportato da tutti i componenti di 
connessione al database ed e descritto in "Gestione delle transazioni" a 

pagina 21-6. 

• Utilizzare una passthrough SQL in un componente query per passare istruzioni 
SQL direttamente a un server SQL oppure ODBC remoto. II vantaggio principale 
del passthrough SQL sta nella possibilita di sfruttare le funzionalita avanzate di 
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gestione di transazioni di un particolare server di database, come per esempio la 
cache di schema. Per capire i vantaggi del modello di gestione delle transazioni del 
server di cui si dispone, consultare la documentazione relativa. Per ulteriori 
informazioni sull'utilizzo di passthrough SQL, consultare "Utilizzo di 
passthrough SQL" qui di seguito. 

Quando si lavora su database locali, il componente database serve solo per creare 
transazioni esplicite (i database locali non supportano passthrough SQL). Tuttavia, 
l'impiego di transazioni locali e soggetto a certe limitazioni. Per ulteriori 
informazioni sull'utilizzo di transazioni locali, consultare "Utilizzo delle transazioni 
locali" a pagina 24-33. 

E possibile rendere minimo il numero di transazioni necessarie registrando gli 
aggiornamenti nella cache. Per ulteriori informazioni sugli aggiornamenti registrati 
nella cache, consultare "Utilizzo di un dataset client per registrare in cache gli 
aggiornamenti" a pagina 27-17 e "Utilizzo di BDE per gli aggiornamenti in cache" a 
pagina 24-33. 



Utilizzo di passthrough SQL 



Con passthrough SQL, si utilizza un componente TQuery, TStoredProc o TUpdateSQL per 
inviare direttamente a un server di database remoto un'istruzione di controllo di 
transazione SQL. BDE non elabora l'istruzione SQL. Usando passthrough SQL si 
possono sfruttare direttamente i controlli di transazione offerti dal server, specialmente 
quando sono di tipo non-standard. 

Per per controllare una transazione mediante passthrough SQL, e necessario 

• Installare i driver SQL Links corretti. Se installando C++Builder si era scelta 
l'opzione "Typical", tutti i driver SQL Links risultano gia installati correttamente. 

• Configurare il protocollo di rete. Consultare l'amministratore di rete per ulteriori 
informazioni. 

• Avere accesso a un database situato su un server remoto. 

• Mediante SQL Explorer impostare SQLPASSTHRU MODE a NOT SHARED. 
SQLPASSTHRU MODE specifica se le istruzioni BDE e passthrough SQL possono 
condividere gli stessi collegamenti al database. Nella maggior parte dei casi, 
l'impostazione di SQLPASSTHRU MODE e SHARED AUTOCOMMIT. Tuttavia, e 
impossibile l'uso condiviso di connessioni con il database quando si utilizzano 
istruzioni di controllo di transazione. Per ulteriori informazioni su modi 
SQLPASSTHRU, consultare il file di guida del programma di utilita BDE 
Administration. 

Quando SQLPASSTHRU MODE e NOT SHARED, e necessario utilizzare dei 
componenti database distinti per i dataset che passano istruzioni di transazione SQL 
al server e per quelli che non lo fanno. 
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Utilizzo delle transazioni locali 



BDE supporta transazioni locali con tabelle Paradox, dBASE, Access e FoxPro. Dal 
punto di vista di chi programma, non c'e differenza fra una transazione locale e una 
transazione con un server di database remote 

Quando si utilizzano transazioni con tabelle locali Paradox, dBASE, Access e FoxPro, 
impostare Translsolation a HDirtyRead invece di utilizzare il valore predefinito di 
tiReadCommitted. Se nel caso di tabelle locali l'impostazione di Translsolation e 
comunque diversa da HDirtyRead viene restituito un errore BDE. 

Quando si inizia una transazione con una tabella locale, gli aggiornamenti eseguiti 
vengono registrati. Ogni record registrato contiene il buffer di un record. Quando 
una transazione e attiva, i record da aggiornare sono bloccati fino a quando la 
transazione non e conclusa o annullata. In caso di rollback, i vecchi buffer dei record 
vengono applicati ai record aggiornati in modo da riportarli alio stato precedente. 

Le transazioni locali sono piu limitate delle transazioni con i server SQL o i driver 
ODBC. In particolare, per le transazioni locali valgono le seguenti limitazioni: 

• Non e fornito il crash recovery automatico. 

• Non sono supportate le istruzioni di definizione dati. 

• Non si possono effettuare transazioni con tabelle temporanee. 

• II livello di Translsolation puo essere solo HDirtyRead. 

• Per Paradox, le transazioni locali possono essere eseguite solo su tabelle che 
abbiano indici validi. Non e possibile il rollback dei dati con tabelle Paradox prive 
di indici. 

• Si puo bloccare e modificare solo un numero limitato di record. Con tabelle 
Paradox, il limite e 255 record. Con tabelle dBASE il limite e 100. 

• Le non si possono eseguire transazioni con il driver ASCII BDE. 

• Se si chiude un cursore su una tabella durante una transazione se ne determina il 
rollback a meno che: 

• Non ci siano piu tabelle aperte. 

• II cursore venga chiuso su una tabella che non ha subito modifiche. 

Utilizzo di BDE per gli aggiornamenti in cache 



L'approccio consigliato per utilizzare gli aggiornamenti in cache consiste nell'usare 
un dataset client (TBDEClientDataSet) o nel collegare il dataset BDE a un dataset 
client utilizzando un provider di dataset. I vantaggi dell'utilizzo di un dataset client 
sono discussi in "Utilizzo di un dataset client per registrare in cache gli 
aggiornamenti" a pagina 27-17. 

Nei casi semplici, tuttavia, si puo invece decidere di registrare gli aggiornamenti in 
cache ricorrendo a BDE. I dataset per BDE e i componenti TDatabase dispongono di 
proprieta , di metodi e di eventi per gestire gli aggiornamenti in cache. Nella maggior 
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parte dei casi, questi corrispondono direttamente alle proprieta , ai metodi e agli 
eventi che si usano con i dataset client e con i dataset provider quando si ricorre a un 
dataset client per la gestione degli aggiornamenti in cache. La seguente tabella elenca 
queste proprieta , questi eventi e questi metodi accanto alle proprieta , i metodi e gli 
eventi corrispondenti di TBDEClientDataSet: 

Tabella 24.6 Proprieta , metodi ed eventi degli aggiornamenti in cache 



Su dataset BDE 






(o TDatabase) 


Su TBDEClientDataSet 


Scopo 


Cachedllpdates 


Non necessario per i 


Determina se gli aggiornamenti in cache 




dataset client, che usano 


sono attivi per il dataset. 




sempre gli aggiornamenti 






in cache. 




UpdateObject 


Usare un gestore di 


Specifica l'oggetto update per 




evento 


l'aggiornamento di dataset di sola 




BeforellpdateRecord, o, se si 


lettura. 




utilizza TClientDataSet, 






usare la proprieta 






UpdateObject del dataset 






sorgente per BDE. 




UpdatesPending 


ChangeCount 


Indica se la cache locale contiene record 
aggiornati che devono essere applicati al 
database. 


UpdateRecordTypes 


Status! titer 


Indica il genere di record aggiornati da 
rendere visibili quando si applicano gli 
aggiornamenti messi nella cache. 


UpdateStatus 


UpdateStatus 


Indica se un record e invariato, 
modificato, inserito o cancellato. 


OnllpdateError 


OnReconcileError 


Evento per la gestione record per record 
degli errori di aggiornamento - 


OnUpda teRecord 


BeforellpdateRecord 


Evento per l'elaborazione record per 
record degli aggiornamenti. 


ApplyUpdates 


ApplyUpdates 


Applica al database i record presenti 


ApplyUpdates (database) 




nella cache locale. 


CancelUpdates 


CancelUpdates 


Elimina dalla cache locale tutti gli 
aggiornamenti senza applicarli. 


CommitUpdates 


Reconcile 


Svuota la cache di aggiornamento dopo 
la conclusione favorevole degli 
aggiornamenti. 


FetchAll 


GetNextPacket 


Copia i record nella cache locale per 




(e PacketRecords) 


modificarli e aggiornarli. 


RevertRecord 


RevertRecord 


Annulla gli aggiornamenti del record 
attivo se non sono stati ancora applicati. 



Per una panoramica dei processi di aggiornamento mediante la cache, consultare 
"Panoramica sull'utilizzo degli aggiornamenti in cache" a pagina 27-18. 

Anche se si utilizza un dataset client per la gestione degli aggiornamenti in cache, e 
utile leggere la sezione sugli oggetti update a pagina 24-41. Si possono utilizzare gli 
oggetti update nel gestore di evento BeforellpdateRecord di TBDEClientDataSet o di 
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TDataSetProvider per applicare aggiornamenti provenienti da procedure registrate o 
da query su piu tabelle. 

Attivazione degli aggiornamenti in cache con BDE 



Per utilizzare BDE per gli aggiornamenti in cache, il dataset per BDE deve indicare 
l'intenzione di mettere gli aggiornamenti nella cache. Lo si specifica impostando la 
proprieta CachedUpdates a true. Quando l'aggiornamento dei dati memorizzati nella 
cache e attivo, nella memoria locale viene posta una copia di tutti i record. Gli utenti 
visualizzano e modificano la copia locale dei dati. Nella cache vengono registrate 
anche le modifiche, gli inserimenti e le cancellazioni che si accumulano in memoria 
fino a quando l'applicazione non li applica al server di database. Se le modifiche 
vanno a buon fine, nella cache i record modificati vengono scaricati dalla memoria. 

II dataset mette nella cache tutti gli aggiornamenti, fino a quando non si imposta 
CachedUpdates a false. L'applicazione delle modifiche presenti nella cache non 
disabilita gli ulteriori aggiornamenti memorizzati, ma trascrive solo nel database 
l'insieme di modifiche corrente e le scarica dalla memoria. Se si annullano gli 
aggiornamenti chiamando CancelUpdates, tutte le modifiche presenti nella cache 
vengono annullate, senza pero impedire al dataset di mettere nella cache le 
modifiche successive. 

Se si disattiva l'aggiomamento in cache impostando CachedUpdates a false, le 
eventuali modifiche non ancora applicate vengono eliminate senza notifica. Per 
evitare la perdita di modifiche, testare la proprieta Updates? 'ending prima di 
disattivare l'aggiornamento in cache. 

Applicazione degli aggiornamenti in cache basati su BDE 



L'applicazione degli aggiornamenti e un processo in due fasi che dovrebbe verificarsi 
nel contesto della transazione di un componente database, in modo che 
l'applicazione possa ristabilirsi convenientemente da errori. Per informazioni sulla 
gestione delle transazioni nel caso dei componenti database, consultare "Gestione 
delle transazioni" a pagina 21-6. 

Applicando gli aggiornamenti sotto il controllo delle transazioni si verifica quanto 
segue: 

1 Viene attivata una transazione con il database. 

2 Gli aggiornamenti nella cache vengono trascritti nel database (fase 1). Se si fornisce 
un evento OnUpdateRecord, questo viene attivato una volta ogni volta che nel 
database viene trascritto un record. Se la trascrizione produce un errore, viene 
attivato l'evento OnUpdateError, se previsto. 

3 La transazione viene confermata se la trascrizione va a buon fine, o annullata in 
caso contrario: 

Se la trascrizione va a buon fine: 

• Le modifiche apportate al database vengono confermate e la transazione si 
conclude. 
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• Gli aggiornamenti nella cache vengono confermati e il buffer inferno della cache 
viene scaricato (fase 2). 

Se la trascrizione non va a buon fine: 

• Le modifiche al database vengono annullate e la transazione si conclude. 

• Gli aggiornamenti presenti nella cache non vengono confermati e rimangono 
nella cache interna. 

Per informazioni sulla creazione e sull'impiego dei gestori di evento OnllpdateRecord, 
consultare "Creazione di un gestore di evento OnUpdateRecord" a pagina 24-38. Per 
informazioni sulla gestione degli errori di aggiornamento che si verificano quando si 
applicano gli aggiornamenti in cache, consultare "Gestione degli errori di 
aggiornamento" a pagina 24-39. 

L'applicazione degli aggiornamenti in cache e un'operazione particolarmente 
delicata quando si ha a che fare con piu dataset collegati secondo una relazione 
master/ detail perche e significativo l'ordine di applicazione degli aggiornamenti a 
ciascun dataset. Di solito, e necessario aggiornare le tabelle master prima di quelle di 
dettaglio, salvo quando si ha a che fare con record cancellati, perche allora l'ordine va 
invertito. A causa di questa difficolta , si raccomanda vivamente l'impiego di dataset 
client quando si mettono in cache gli aggiornamenti di una scheda master/ detail. I 
dataset client gestiscono automaticamente tutte le questioni di ordinamento nelle 
relazioni master /detail. 

Ci sono due modi per applicare gli aggiornamenti basati su BDE: 

• Un modo e quello di applicare gli aggiornamenti utilizzando un componente 
database e chiamando il suo metodo ApplyUpdates. Questo e l'approccio piu 
semplice, perche il database gestisce tutti i dettagli del processo di transazione e 
scarica la cache ad aggiornamento concluso. 

• E possibile aggiornare un singolo dataset chiamando i suoi metodi Applyllpdates e 
CommitUpdates. In questo caso, e necessario codificare esplicitamente la 
transazione che interessa il processo di aggiornamento, come pure chiamare 
esplicitamente CommitUpdates per confermare gli aggiornamenti provenienti dalla 
cache. 

Per applicare gli aggiornamenti da una procedura registrata o da una query SQL che 
non restituisce un set risultato "live", e necessario utilizzare TUpdateSQL per 
specificare come eseguire gli aggiornamenti. Per aggiornamenti a concatenamenti 
(query implicanti due o piu tabelle), e necessario fornire un oggetto TUpdateSQL per 
ogni tabella coin vol ta, e utilizzare il gestore di evento OnUpdateRecord per ri chiamare 
questi oggetti in modo da eseguire gli aggiornamenti. Consultare "Aggiornamento di 
dataset mediante oggetti update" a pagina 24-41 per i dettagli. 

Applicazione degli aggiornamenti nella cache mediante un database 

Per applicare nel contesto di una connessione con un database gli aggiornamenti 
presenti nella cache a uno o piu dataset, si usa il metodo ApplyUpdates del 
componente database. II seguente codice applica degli aggiornamenti al dataset 
Customer sQuery in risposta all'evento clic di un pulsante: 

void __fastcall TForml: :ApplyButtonClick(TObject *Sender) 
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{ 

// for local databases such as Paradox, dBASE, and FoxPro 
// set Transudation to DirtyRead 

if ( !Databasel->IsSQLBased && Databasel->TransIsolation != tiDirtyRead) 

Databasel->TransIsolation = tiDirtyRead; 
Databasel->ApplyUpdates (fcCustomersQuery, 0) ; 

} 

Con le righe precedenti si trascrivono nel database gli aggiornamenti presenti nella 
cache nel contesto di una transazione generata automaticamente. Se l'operazione ha 
successo, la transazione viene confermata e poi vengono confermati gli 
aggiornamenti nella cache. In caso contrario, si ha l'annullamento della transazione e 
la cache rimane invariata. In questo secondo caso, gli errori dovuti agli 
aggiornamenti in cache andrebbero gestiti mediante l'evento OnllpdateError del 
dataset. Per ulteriori informazioni sulla gestione degli errori di aggiornamento, 
consultare "Gestione degli errori di aggiornamento" a pagina 24-39. 

II vantaggio principale della chiamata del metodo Applyllpdates di un componente 
database e la possibility di aggiornamento di qualsiasi numero di componenti dataset 
associati al database. I due argomenti per il metodo Applyllpdates di un database 
sono un array di TDBDataSet, e l'indice dell'ultimo dataset neU'array. Per applicare 
gli aggiornamenti per piu di un dataset, creare un array locale di puntatori ai dataset. 
Ad esempio, il seguente codice applica gli aggiornamenti di due query: 

TDBDataSet* ds[] = {CustomerQuery, OrdersQuery} ; 

if ( !Databasel->IsSQLBased && Databasel->Translsolation != tiDirtyRead) 

Databasel->TransIsolation = tiDirtyRead; 
Databasel->ApplyUpdates (ds, 1) ; 

Applicazione degli aggiornamenti in cache con i metodi dei componenti 
dataset 

E possibile aggiornare singoli dataset per BDE tramite i metodi Applyllpdates e 
CommitUpdates del dataset. Ognuno di questi metodi racchiude una fase del processo 
di aggiornamento: 

1 Applyllpdates trascrive in un database le modifiche presenti nella cache (fase 1). 

2 CommitUpdates scarica (cancella) la cache interna quando la trascrizione va a buon 
fine (fase 2). 

II seguente codice illustra come si applicano gli aggiornamenti all'interno di una 
transazione riguardante il dataset CustomerQuery: 

void __fastcall TForml: :ApplyButtonClick(TObject *Sender) 
{ 

Databasel->StartTransaction() ; 
try 

{ 

if ( !Databasel->IsSQLBased && Databasel->Translsolation != tiDirtyRead) 

Databasel->TransIsolation = tiDirtyRead; 
CustomerQuery->ApplyUpdates () ; // try to write the updates to the database 
Databasel->Commit ( ) ; // on success, commit the changes 

} 

catch (...) 
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{ 

Databasel->Rollback( ) ; // on failure, undo any changes 

throw; // throw the exception again to prevent a call to CommitUpdates 

} 

CustomerQuery->CommitUpdates () ; // on success, clear the internal cache 

} 

Se durante la chiamata di ApplyUpdates viene sollevata un'eccezione, si ha 
1'annullamento della transazione. II rollback assicura che nella tabella di database 
non vengano trascritte modifiche. L'istruzione throw nel blocco try... catch solleva 
nuovamente l'eccezione, evitando la chiamata a CommitUpdates. Siccome 
CommitUpdates non viene chiamato, la cache interna degli aggiornamenti non viene 
cancellata consentendo di gestire la condizione di errore e, se e il caso, di ritentare 
l'aggiornamento. 

Creazione di un gestore di evento OnUpdateRecord 

Per applicare gli aggiornamenti memorizzati nella sua cache, un dataset per BDE 
esamina in sequenza le modifiche presenti nella cache, e cerca di trascriverle nei 
record corrispondenti nella tabella sottostante. Mentre l'aggiornamento per ogni 
record modificato, cancellato o inserito sta per essere trascritto, viene attivato 
l'evento OnUpdateRecord del componente dataset. 

Se si prepara un gestore per l'evento OnUpdateRecord si ha la possibility di eseguire 
determinate azioni prima dell'effettiva trascrizione dell'aggiornamento del record 
corrente. Tra queste vi possono essere una convalida speciale dei dati, 
l'aggiornamento di altre tabelle, la sostituzione speciale di parametri, o l'esecuzione 
di piu oggetti update. Un gestore di evento OnUpdateRecord consente di controllare 
meglio il processo di aggiornamento. 

Ecco lo schema del codice di un gestore di evento OnUpdateRecord: 

void __fastcall TForml: :DataSetUpdateRecord(TDataSet *DataSet, 
TUpdateKind UpdateKind, TUpdateAction SUpdateAction) 

{ 

// Perform updates here... 

} 

II parametro DataSet specifica il dataset memorizzato nella cache con gli 
aggiornamenti. 

II parametro UpdateKind indica il tipo di aggiornamento da eseguire sul record attivo. 

I valori di UpdateKind sono ukModify, uklnsert e ukDelete. Se si utilizza un oggetto 
update, e necessario passare questo parametro all'oggetto update quando 
l'aggiornamento viene trascritto. Puo anche essere necessario esaminare il parametro 
se il gestore esegue qualche elaborazione speciale in base al genere di 
aggiornamento. 

II parametro UpdateAction indica se l'aggiornamento e stato applicato. I valori di 
UpdateAction sono uaFail (l'impostazione predefinita), uaAbort, uaSkip, uaRetry, 
uaApplied. Se il gestore di evento porta a buon fine l'aggiornamento, prima di uscire il 
parametro deve diventare uaApplied. Se si decide di non aggiornare il record attivo, si 
deve il valore di uaSkip per lasciare nella cache le modifiche non attuate. Se non si 
modifica il valore di UpdateAction, l'intera operazione di aggiornamento del dataset 
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si interrompe e viene sollevata un'eccezione. E possibile sopprimere il messaggio di 
errore (sollevando un'eccezione tacita) se si cambia UpdateAction in uaAbort. 

Oltre a questi parametri, normalmente si utilizzano le proprieta OldValue e NewValue 
del componente campo associato al record attivo. OldValue da il valore originario del 
campo che e stato prelevato dal database. Puo essere utile nell'individuare il record 
di database da aggiornare. NewValue e il valore modificato dell'aggiornamento che si 
cerca di trascrivere. 

II gestore di evento OnUpdateRecord, proprio come il gestore di evento OnUpdateError 
o OnCalcFields, non dovrebbe mai chiamare metodi che modificano il record attivo di 
un dataset. 

II seguente esempio illustra come utilizzare questi parametri e queste proprieta . Per 
applicare gli aggiornamenti utilizza un componente TTable chiamato UpdateTable. 
Nella pratica, e piu facile utilizzare un oggetto update, ma usare una tabella illustra 
le possibility piu chiaramente. 

void __fastcall TForml: :EmpAuditUpdateRecord(TDataSet *DataSet, 
TUpdateKind UpdateKind, TUpdateAction &UpdateAction) 

{ 

if (UpdateKind == uklnsert) 

{ 

TVarRec values [2] ; 

for (int i = 0; i < 2; i++) 

values [i] = DataSet->Fields->Fields [i] ->NewValue; 
UpdateTable->AppendRecord (values, 1) ; 

} 

else 

{ 

TLocateOptions lo; 
lo. Clear (); 

if (UpdateTable->Locate("KeyField n , DataSet->Fields->Fields [0] ->01dValue, lo)) 
switch (UpdateKind) 
{ 

case ukModify: 
UpdateTable->Edit() ; 

UpdateTable->Fields->Fields [1] ->Value = DataSet->Fields->Fields [1] ->Value; 
UpdateTable->Post() ; 
break ; 
case ukDelete: 
UpdateTable->Delete() ; 
break ; 

Gestione degli errori di aggiornamento 

Borland Database Engine (BDE) controlla specificatamente i conflitti di 
aggiornamento e altre condizioni quando tenta di applicare gli aggiornamenti e 
riporta gli errori. L'evento OnUpdateError del componente dataset consente di 
rilevare e di rispondere agli errori. Se si utilizzano gli aggiornamenti in cache si 
dovrebbe creare un gestore di questo evento. In caso contrario, quando si verifica un 
errore, l'intera operazione di aggiornamento non va a buon fine. 

Ecco lo schema di codice di un gestore di evento OnUpdateError. 
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void __fastcall TForml: :DataSetUpdateError (TDataSet *DataSet, 
EDatabaseError *E, TUpdateKmd UpdateKind, TUpdateAction SUpdateAction) 

{ 

// Respond to errors here... 

} 

DataSet fa riferimento al dataset a cui sono applicati gli aggiornamenti. E possibile 
utilizzarlo in fase di gestione degli errori per accedere a nuovi e a vecchi valori. I 
valori originali dei campi di ciascun record sono memorizzati nella proprieta di sola 
lettura TField chiamata OldValue, mentre quelli modificati sono memorizzati nella 
proprieta analoga di TField chiamata NewValue. Questi valori sono l'unico modo per 
esaminare e modificare i valori di aggiornamento del gestore di evento 

Non chiamare metodi di dataset (come Next e Prior) che modificano il record attivo, 
perche si farebbe entrare in un loop infinito il gestore di evento. 

Di solito il parametro E e del tipo EDBEngineError. Da questo tipo di eccezione, si puo 
estrarre un messaggio di errore che e possibile mostrare agli utenti nel gestore di 
errore. Ad esempio, si potrebbe usare questo codice per visualizzare un messaggio di 
errore nell'intestazione di una finestra di dialogo: 

ErrorLabel->Caption = E->Message; 

Questo parametro e anche utile per stabilire la causa effettiva dell'errore di 
aggiornamento. E possibile estrarre degli specifici codici di errore da EDBEngineError 
e in base ad essi eseguire l'azione appropriata. 

II parametro UpdateKind descrive il tipo di aggiornamento che ha generato l'errore. A 
meno che il gestore di errore non esegua azioni speciali in base a il tipo di 
aggiornamento eseguito, probabilmente il codice non fara uso di questo parametro. 

La seguente tabella elenca i possibili valori di UpdateKind: 



Tabella 24.7 Valori di UpdateKind 




ukModify La modifica di un record esistente ha causato un errore. 

uklnsert L'inserimento di un nuovo record ha causato un errore. 

ukDelete La cancellazione di un record esistente ha causato un errore. 



UpdateAction indica a BDE come portare avanti il processo di aggiornamento quando 
il gestore di evento si chiude. Quando il gestore di evento viene chiamato, il valore di 
questo parametro e sempre uaFail. In base alia condizione di errore del record che ha 
causato l'errore e all'azione intrapresa per rimediare, solitamente prima di uscire dal 
gestore a UpdateAction viene attribuito un valore diverso: 

• Se il gestore di errore puo correggere la condizione di errore che ha fatto 
richiamare il gestore, si imposta UpdateAction in modo che svolga l'azione 
appropriata alTuscita. Per le condizioni di errore che e possibile correggere, 
impostare UpdateAction a uaRetry per richiedere nuovamente l'aggiornamento del 
record.. 
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• Quando l'impostazione e uaSkip, l'aggiornamento della riga che ha causato 
l'errore viene saltato e l'aggiornamento del record rimane nella cache dopo il 
completamento di tutti gli altri aggiornamenti. 

• Sia uaFail che uaAbort determinano la conclusione dell'intera operazione di 
aggiornamento. uaFail solleva un'eccezione e visualizza un messaggio di errore. 
uaAbort solleva un'eccezione silenziosa (non visualizza un messaggio di errore). 

II seguente codice visualizza un gestore di evento OnUpdateError che verifica se 
l'errore di aggiornamento e relativo a una violazione di chiave e, in caso positivo, 
imposta il parametro UpdateAction a uaSkip: 

II include BDE.hpp in your unit file for this example 

void __fastcall TForml: :DataSetUpdateError (TDataSet *DataSet, 
EDatabaseError *E, TUpdateKmd UpdateKind, TUpdateAction SUpdateAction) 

{ 

UpdateAction = uaFail // initialize to fail the update 
if (E->ClassNameIs ( "EDBEngineError" ) ) 

{ 

EDBEngineError *pDBE = (EDBEngineError *)E; 

if (pDBE->Errors [pDBE->ErrorCount - 1] ->ErrorCode == DBIERR_KEYVIOL ) 
UpdateAction = uaSkip; // Key violation, just skip this record 

} 

} 

Se durante l'applicazione degli aggiornamenti in cache si verifica un errore, viene 
sollevata un'eccezione e appare un messaggio di errore. Salvo il caso in cui 
ApplyUpdates viene chiamato dall'interno di un ciclo try.. .catch, il messaggio di errore 
visualizzato all'utente da dentro il gestore di evento OnllpdateError puo apparire 
ancora una volta. Per evitare la ripetizione bisogna dare a UpdateAction il valore 
uaAbort e disattivare la comparsa del messaggio di errore di sistema. 

Aggiornamento di dataset mediante oggetti update 



Quando il dataset per BDE rappresenta una procedura registrata o una query che 
non restituisce risultati "live", non si possono effettuare aggiornamenti direttamente 
dal dataset. Infatti si potrebbero verificare problemi quando si utilizza un dataset 
client per mettere in cache gli aggiornamenti. In ambedue i casi, si evita il problema 
utilizzando un oggetto update: 

1 Se si utilizza un dataset client, ricorrere a un componente provider esterno con 
TClientDataSet, piuttosto che a TBDEClientDataSet. Questo per consentire di 
impostare la proprieta UpdateObject del dataset sorgente per BDE (punto 3). 

2 Aggiungere un componente TUpdateSQL al modulo dati del dataset per BDE. 

3 Impostare la proprieta UpdateObject del componente dataset per BDE al 
componente TUpdateSQL nel modulo dati. 

4 Specificare le istruzioni SQL necessarie per eseguire gli aggiornamenti tramite le 
proprieta ModifySQL, InsertSQL e DeleteSQL dell'oggetto update. L'editor Update 
SQL aiuta a scrivere queste istruzioni. 

5 Chiudere il dataset. 
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6 Assegnare il valore true alia proprieta CachedUpdates del componente dataset o 
collegare il dataset con il dataset client utilizzando un provider di dataset. 

7 Riaprire il dataset. 

Talvolta, e necessario utilizzare piu oggetti update. Ad esempio, quando si aggiorna 
una join su piu tabelle o una procedura registrata che rappresenta dati provenienti da 
piu dataset, bisogna fornire un oggetto TUpdateSQL a ogni tabella da aggiornare. 
Quando si utilizzano piu oggetti update, non si puo semplicemente associare 
l'oggetto update al dataset tramite la proprieta UpdateObject. Invece, si deve chiamare 
manualmente l'oggetto update da un gestore di evento OnllpdateRecord (se si utilizza 
BDE per memorizzare gli aggiornamenti nella cache) o da un gestore di evento 
BeforeUpdateRecord (se si utilizza un dataset client). 

L'oggetto update in effetti incorpora tre componenti TQuery, ognuno dei quali 
esegue una sola operazione di aggiornamento. Uno fornisce un'istruzione SQL 
UPDATE per la modifica di record esistenti; un secondo fornisce un'istruzione 
INSERT per aggiungere nuovi record a una tabella; e un terzo fornisce un'istruzione 
DELETE per eliminare i record da una tabella. 

Quando si mette un componente update in un modulo dati, i componenti query che 
esso racchiude non si vedono. Essi vengono creati in fase di esecuzione dal 
componente update in base a tre proprieta di aggiornamento per le quali vanno 
fornite le istruzioni SQL: 

• ModifySQL specifica l'istruzione UPDATE. 

• InsertSQL specifica l'istruzione INSERT. 

• DeleteSQL specifica l'istruzione DELETE. 

In fase di esecuzione, quando il componente update viene usato per trascrivere gli 
aggiornamenti: 

1 Seleziona un'istruzione SQL da eseguire a seconda che il record attivo venga 
modificato, inserito o cancellato. 

2 Fornisce valori del parametro all'istruzione SQL. 

3 Prepara ed esegue l'istruzione SQL in modo da farle portare a termine 
l'aggiornamento specificato. 

Creazione di istruzioni SQL per componenti update 

Per aggiornare un record di un dataset associate un oggetto update utilizza una di 
tre istruzioni SQL. Ogni oggetto update puo aggiornare solo una singola tabella, 
cosicche ciascuna istruzione di aggiornamento dell'oggetto deve fare riferimento alia 
stessa tabella base. 

Le tre istruzioni SQL rispettivamente cancellano, inseriscono e modificano i record 
nella cache. Le istruzioni vanno fornite sotto forma di proprieta DeleteSQL, InsertSQL 
e ModifySQL. I valori possono essere forniti in fase di progetto o di esecuzione. Ad 
esempio, il seguente codice specifica in fase di esecuzione il valore della proprieta 
DeleteSQL: 

UpdateSQL->DeleteSQL->Clear() ; 

UpdateSQL->DeleteSQL->Add( "DELETE FROM Inventory I"); 



24-42 Guida alia programmazione 



Utilizzo di BDE per gli a g g i o r n a m e n t i in cache 

UpdateSQL->DeleteSQL->Add( "WHERE (I.IteitiHo = :OLD_IterrMo) ") ; 

In fase di progettazione, l'editor Update SQL aiuta a scrivere le istruzioni SQL con 
cui si applicano gli aggiornamenti. 

Gli oggetti update forniscono una connessione di parametro automatica nel caso dei 
parametri che referenziano i valori di campo originali e aggiornati del dataset. Di 
solito, quindi, quando si scrivono le istruzioni SQL si inseriscono parametri con nomi 
che hanno un formato speciale. Per informazioni sull'uso di questi parametri, 
consultare "Sostituzione dei parametri nelle istruzioni di aggiornamento SQL" a 
pagina 24-44. 

Utilizzo di Update SQL editor 

Per scrivere le istruzioni SQL di un componente update, 

1 Mediante l'Object Inspector, selezionare il nome dell'oggetto update nella lista a 
discesa della proprieta UpdateObject del dataset. In questo modo, l'Update SQL 
editor che verra richiamato nel passo successivo e in grado di determinare i valori 
predefiniti da utilizzare con le opzioni di generazione SQL. 

2 Fare clic con il pulsante destro sull'oggetto update e selezionare 1'UpdateSQL 
Editor nel menu di scelta rapida. Appare l'editor Update SQL, con cui si creano le 
istruzioni SQL delle proprieta ModifySQL, InsertSQL e DeleteSQL dell'oggetto 
update in base al dataset inerente e ai valori che gli vengono forniti. 

L'editor Update SQL ha due pagine. La pagina Options appare quando l'editor viene 
richiamato. Per selezionare la tabella da aggiornare utilizzare la casella combinata 
Table Name. Quando si indica il nome della tabella, nelle caselle di riepilogo Key 
Fields e Update Fields appaiono tutte le colonne disponibili. 

La casella di riepilogo Update Fields indica quali colonne aggiornare. Quando si 
specifica la tabella, appaiono selezionate tutte le colonne della casella di riepilogo 
Update Fields. Si possono selezionare piu campi in base alle esigenze. 

La casella di riepilogo Key Fields serve per specificare le colonne da usare come 
chiave neU'aggiomamento. Nel caso di tabelle Paradox, dBASE e FoxPro, le colonne 
specificate devono corrispondere a un indice esistente, cosa non obbligatoria nel caso 
di database SQL remoti. Invece di impostare Key Fields, facendo clic sul pulsante 
Primary Keys si scelgono i campi chiave di aggiornamento in base all'indice 
principale della tabella. Facendo clic su Dataset Defaults si riportano le liste di 
selezione alio stato originario: tutti i campi sono selezionati come chiavi e tutti i 
campi sono selezionati per l'aggiornamento. 

Spuntare la casella di controllo Quote Field Names se il server vuole che i nomi di 
campo siano messi tra virgolette. 

Una volta specificata la tabella si selezionano le colonne chiave e le colonne da 
aggiornare, poi facendo clic su Generate SQL si generano le istruzioni preliminari 
SQL da associare alle proprieta ModifySQL, InsertSQL e DeleteSQL del componente 
update. Nella maggior parte dei casi, e preferibile o necessario mettere a punto le 
istruzioni SQL generate automaticamente. 

Per visualizzare e modificare le istruzioni SQL generate, selezionare la pagina SQL. 
Se sono state generate delle istruzioni SQL, quando la pagina viene selezionata, 
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l'istruzione relativa alia proprieta ModifySQL e gia visibile nel riquadro SQL Text. 
Tale istruzione puo essere modificata in base alle prorie esigenze. 

Ricordare che le istruzioni SQL generate sono punti di partenza di creare le istruzioni 
di aggiornamento. In certi casi, bisogna modificarle per farle eseguire correttamente. 
Ad esempio, quando si gestiscono dati contenenti valori NULL, e necessario 
modificare la clausola WHERE in modo che sia 

WHERE field IS NULL 

invece di usare la variabile di campo generata. Ognuna delle istruzioni va testata 
personalmente prima di essere accettata. 

Per commutare tra le istruzioni SQL generate e modificarle in base alle esigenze, 
utilizzare i pulsanti di scelta Statement Type. 

Per accettare le istruzioni e associarle alle proprieta SQL del componente update, fare 
clic su OK. 

Sostituzione dei parametri nelle istruzioni di aggiornamento SQL 

Le istruzioni di aggiornamento SQL ricorrono a una forma particolare di sostituzione 
di parametro che permette di sostituire vecchi o nuovi valori di campo negli 
aggiornamenti dei record. L'editor Update SQL quando genera le sue istruzioni, 
determina quali valori di campo utilizzare. Quando si scrive l'aggiornamento SQL, si 
specificano i valori del campo da utilizzare. 

Quando il nome del parametro corrisponde a un nome di colonna nella tabella, viene 
automaticamente utilizzato come valore del parametro il nuovo valore del campo 
nell'aggiornamento presente nella cache del record. Quando il nome del parametro 
corrisponde a quello di una colonna ed e preceduto dalla stringa "OLD_", viene 
usato il vecchio valore del campo. Ad esempio, nell'istruzione di aggiornamento SQL 
qui di seguito, il parametro UastName viene riempito automaticamente con il nuovo 
valore del campo presente nell'aggiornamento in cache per il record inserito. 

INSERT INTO Names 

(LastName, FirstName, Address, City, State, Zip) 
VALUES (:LastName, :FirstName, :Address, :City, :State, :Zip) 

Nuovi valori di campo vengono solitamente usati nelle istruzioni Insert SQL e 
ModifySQL. Nell'aggiornamento di un record modificato, il nuovo valore di campo 
preso dalla cache viene utilizzato dall'istruzione UPDATE per sostituire il vecchio 
valore di campo nella tabella base aggiornata. 

Nel caso di record cancellati, non c'e nessun nuovo valore, cosicche la proprieta 
DeleteSQL utilizza la sintassi ":OLD_FieldName". I vecchi valori del campo vengono 
normalmente usati anche nella clausola WHERE dell'istruzione SQL per gli 
aggiornamenti di modifica o di cancellazione, in modo da stabilire quali record 
aggiornare o cancellare. 

Nella clausola WHERE di un'istruzione UPDATE o DELETE bisogna fornire almeno 
il numero minimo di parametri per identificare univocamente il record nella tabella 
base da aggiornare con i dati della cache. Per esempio, in una lista di clienti, il solo 
cognome di un cliente potrebbe non essere sufficiente a identificare univocamente 
nella tabella base il record corretto; potrebbero esserci molti record che hanno 
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"Smith" come cognome. Invece, i parametri del cognome, del nome e del numero di 
telefono potrebbero rappresentare una combinazione univoca. Meglio ancora 
sarebbe un valore univoco del campo come l'identificativo cliente. 

Se si creano istruzioni SQL contenenti parametri che non rimandano i valori del 
campo modificati oppure originali, l'oggetto update non sa come collegare i loro 
valori. Tuttavia, lo si puo fare manualmente, mediante la proprieta Query 
dell'oggetto update. Per i dettagli fare riferimento a "Utilizzo della proprieta Query 
di un componente update" a pagina 24-49. 

Stesura di istruzioni SQL di aggiornamento 

In fase di progettazione, l'editor Update SQL puo servire a scrivere le istruzioni SQL 
per le proprieta DeleteSQL, InsertSQL e ModifySQL. Se non lo si usa o se si desidera 
modificare le istruzioni generate, e bene aver presenti questi criteri quando si 
scrivono le istruzioni per cancellare, inserire e modificare i record nella tabella base. 

La proprieta DeleteSQL deve contenere solo un'istruzione SQL con il comando 
DELETE. La tabella base da aggiornare deve essere indicata nella clausola FROM. Per 
fare in modo che l'istruzione SQL cancelli nella tabella di base solo il record che 
corrisponde al record cancellato nella cache di aggiornamento, si utilizza una 
clausola WHERE. Nella clausola WHERE, si usa un parametro relativo a uno o piu 
campi che consenta di identificare univocamente nella tabella di base il record 
corrispondente al record da aggiornare nella cache. Se i parametri hanno lo stesso 
nome del campo e sono preceduti da "OLD_", assumono automaticamente i valori 
dal campo corrispondente del record da aggiornare memorizzato nella cache. Se i 
parametri hanno un qualsiasi altro nome, e necessario fornirne i valori. 

DELETE FROM Inventory I 
WHERE (I.ItemNo = :OLD_ItemNo) 

Alcuni tipi di tabella potrebbero non essere in grado di trovare il record nella tabella 
base, quando i campi utilizzati per identificare il record contengono valori NULL. In 
questi casi, l'aggiornamento per cancellazione non va a buon fine. Per ovviare a 
questa situazione, bisogna aggiungere una condizione ai campi che potrebbero 
contenere valori NULL utilizzando il predicato IS NULL (oltre a una condizione per i 
valori non-NULL). Ad esempio, quando un campo FirstName puo contenere un 
valore NULL: 

DELETE FROM Names 

WHERE (LastName = :OLD_LastName) AND 

((FirstName = :OLD_FirstName) OR (FirstName IS NULL)) 

L'istruzione InsertSQL deve contenere solo un'istruzione SQL con il comando 
INSERT. La tabella base da aggiornare deve essere indicata nella clausola INTO. 
Nella clausola VALUES, va fornita una lista di parametri separati da virgole. Se i 
parametri hanno lo stesso nome del campo, ricevono automaticamente il valore del 
record di aggiornamento memorizzato nella cache. Se i nomi sono diversi, bisogna 
fornire i valori del parametro. La lista di parametri fornisce i valori dei campi del 
record appena inserito. II numero di parametri deve essere uguale a quello dei campi 
elencati nell'istruzione. 

INSERT INTO Inventory 
(ItemNo, Amount) 
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VALUES (:ItemNo, 0) 

Nell'istruzione Modify SQL ci deve essere solo un'istruzione SQL con il comando 
UPDATE. La tabella base da aggiornare va chiamata nella clausola FROM. Nella 
clausola SET si includono una o piu assegnazioni di valore. Se i valori presenti nella 
clausola SET sono parametri il cui nome e uguale a quello dei campi, i parametri 
ricevono automaticamente i valori dei campi con lo stesso nome presenti nel record 
aggiornato nella cache. Si possono assegnare ulteriori valori di campo mediante altri 
parametri, purche i nomi siano diversi e i valori siano indicati manualmente. Come 
con l'istruzione DeleteSQL, va fornita una clausola WHERE per verificare 
univocamente il record da aggiornare utilizzando parametri con lo stesso nome dei 
campi ma preceduti da "OLD_". Nell'istruzione di aggiornamento qui di seguito, il 
parametro :ItemNo riceve automaticamente un valore mentre :Price non lo riceve. 

UPDATE Inventory I 

SET I.ItemNo = : ItemNo, Mount = : Price 
WHERE (I.ItemNo = :OLD_ItemNo) 

Considerando l'aggiornamento SQL precedente, ecco un esempio dove l'utente 
modifica un record esistente. II valore originale del campo ItemNo e 999. In una 
griglia connessa al dataset memorizzato nella cache, l'utente fa diventare 123 il valore 
del campo ItemNo 123 mentre Amount diventa 20. Quando si richiama il metodo 
ApplyUpdates, questa istruzione SQL agisce su tutti i record della tabella base in cui 
il campo ItemNo e 999, utilizzando il vecchio valore del campo nel parametro 
:OLD_itemno. Nei record interessati, cambia il valore del campo ItemNo in 123 
(utilizzando il parametro :ItemNo, il valore preso dalla griglia) mentre Amount 
diventa 20. 

Utilizzo di piu oggetti update 

Quando si devono aggiornare piu tabelle base referenziate nel dataset, bisogna usare 
piu oggetti update: uno per ciascuna tabella base aggiornata. Poiche UpdateObject del 
componente dataset consente di associare al dataset un solo oggetto update, e 
necessario associare a ciascun oggetto un dataset, assegnando alia sua proprieta 
DataSet il nome del dataset. 

Quando si utilizzano piu oggetti update, e possibile usare TBDEClientDataSet invece 
di TCHentDataSet con un provider esterno. Questo perche non si deve impostare la 
proprieta UpdateObject del dataset sorgente. 

In fase di progetto, nell'Object Inspector non e disponibile la proprieta DataSet degli 
oggetti update. La si puo impostare solo in fase di esecuzione. 

UpdateSQLl->DataSet = Queryl; 

L'oggetto update utilizza questo dataset per ottenere i valori di campi originali e 
aggiornati per la sostituzione di parametro e, se si tratta di un dataset per BDE, per 
verificare la sessione e il database da usare quando si trascrivono gli aggiornamenti. 
Per far funzionare correttamente la sostituzione di parametro, la proprieta DataSet 
dell'oggetto update deve essere il dataset contenente i valori di campo aggiornati. Se 
si usa un dataset per BDE per gli aggiornamenti in cache, questo e lo stesso dataset 
per BDE. Se si usa un dataset client, questo e un dataset client fornito come 
parametro al gestore di evento BeforeUpdateRecord. 
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Quando l'oggetto update non e stato assegnato alia proprieta UpdateObject del 
dataset, le sue istruzioni SQL non vengono eseguite automaticamente nel momento 
in cui si richiama ApplyUpdates. Per aggiornare i record, bisogna chiamare 
manualmente l'oggetto update da un gestore di evento OnllpdateRecord (se e BDE che 
memorizza gli aggiornamenti nella cache) o da un gestore di evento 
BeforellpdateRecord (se si usa un dataset client). Nel gestore di evento, le azioni 
minime da eseguire sono 

• Se si utilizza un dataset client per memorizzare nella cache gli aggiornamenti, 
bisogna accertarsi che le proprieta DatabaseName e SessionName dell'oggetto da 
aggiornare siano impostate sui valori delle proprieta DatabaseName e SessionName 
del dataset sorgente. 

• II gestore di evento deve chiamare il metodo ExecSQL o Apply dell'oggetto update. 
In questo modo, si richiama l'oggetto update per ciascun record da aggiornare. Per 
ulteriori informazioni sull'esecuzione di istruzioni di aggiornamento, consultare 
"Esecuzione delle istruzioni SQL" qui di seguito. 

• Impostare il parametro UpdateAction del gestore di evento a uaApplied 
(OnllpdateRecord) oppure assegnare il valore true al parametro Applied 
(BeforellpdateRecord). 

Facoltativamente, si possono convalidare o modificare i dati, oppure effettuare altre 
operazioni che dipendono dall'aggiornamento di ciascun record. 

Se in un gestore di evento OnllpdateRecord si chiama il metodo ExecSQL o Apply di un 
oggetto update, accertarsi di non impostare la proprieta UpdateObject del dataset a 
quell'oggetto update, altrimenti seguira un secondo tentativo di aggiornare ogni 
record. 

Esecuzione delle istruzioni SQL 

Quando si usano piu oggetti update, non si deve associarli a un dataset 
impostandone la proprieta UpdateObject. La conseguenza sarebbe che le istruzioni 
appropriate non verrebbero eseguite automaticamente al momento di applicare gli 
aggiornamenti. Invece, l'oggetto update va richiamato esplicitamente scrivendo un 
codice. 

Ci sono due modi per richiamare l'oggetto update. II modo scelto dipende dal fatto se 
l'istruzione SQL utilizza o meno dei parametri per rappresentare i valori del campo: 

• Se l'istruzione SQL da eseguire utilizza parametri, chiamare il metodo Apply. 

• Se l'istruzione SQL da eseguire non utilizza parametri, e meglio chiamare il 
metodo ExecSQL. 

Se l'istruzione SQL utilizza parametri diverso dai tipi incorporati (sia per i valori del 
campo originali che per quelli aggiornati), i valori del parametro vanno forniti 
manualmente invece di basarsi sulla sostituzione di parametro fornita dal metodo 
Apply. Per informazioni su come indicare manualmente i valori dei parametri, vedere 
"Utilizzo della proprieta Query di un componente update" a pagina 24-49. 

Per informazioni sulla sostituzione dei parametri predefiniti nelle istruzioni SQL di 
un oggetto update, vedere "Sostituzione dei parametri nelle istruzioni di 
aggiornamento SQL" a pagina 24-44. 
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Chiamata del metodo Apply 

II metodo Apply di un componente update applica manualmente gli aggiornamenti al 
record attivo. II rpocedimento si svolge in due fasi: 

1 I valori iniziale e modificato del campo del record sono collegati a parametri 
neH'istruzione SQL appropriata. 

2 L'istruzione SQL viene eseguita. 

Per applicare l'aggiornamento del record attivo nella cache di aggiornamento 
chiamare il metodo Apply. II metodo Apply e chiamato molto spesso dall'interno di 
un gestore di evento OnllpdateRecord del dataset o dal gestore di evento 
BeforellpdateRecord di un provider. 

Se si utilizza la proprieta UpdateObject del dataset per associare il dataset e l'oggetto 
update, Apply viene chiamato automaticamente. In questo caso, non bisogna 
chiamarlo in un gestore di evento OnllpdateRecord in quanta vi sarebbe un secondo 
tentativo di applicare l'aggiornamento del record attivo. 

I gestori di evento OnllpdateRecord indicano il tipo di aggiornamento da applicare 
con un parametro UpdateKind di tipo TUpdateKind. II parametro va passato al metodo 
Apply per indicare quale istruzione SQL utilizzare. II seguente codice lo illustra 
utilizzando un gestore di evento BeforellpdateRecord: 

void __fastcall TForml: :BDEClientDataSetlBeforeUpdateRecord(TObject *Sender, 

TDataSet *SourceDS, TCustomClientDataSet *DeltaDS, TUpdateKind UpdateKind, bool &Applied) 

{ 

UpdateSQLl->DataSet = DeltaDS; 

TDBDataSet *pSrcDS = dynamic_cast <TDBDataSet MSourceDS) ; 
UpdateSQLl->DatabaseName = pSrcDS->DatabaseName; 
UpdateSQLl->SessionName = pSrcDS->SessionName; 
UpdateSQLl->Apply (UpdateKind) ; 
Applied = true; 

} 

Chiamata del metodo ExecSQL 

II metodo ExecSQL di un componente update applica manualmente gli 
aggiornamenti al record attivo. A differenza del metodo Apply, ExecSQL non associa 
dei parametri all'istruzione SQL prima di eseguirla. II metodo ExecSQL e chiamato 
molto spesso dall'interno di un gestore di evento OnllpdateRecord (quando si usa 
BDE), oppure BeforellpdateRecord (quando si usa un dataset client). 

Siccome ExecSQL non collega valori di parametro, e usato soprattutto quando le 
istruzioni SQL dell'oggetto update non contengono parametri. In assenza di 
parametri, si puo usare anche Apply, ma ExecSQL e piu efficiente perche non fa la 
verifica dei parametri. 

Se le istruzioni SQL includono parametri, si puo sempre chiamare ExecSQL, ma solo 
dopo aver collegato esplicitamente i parametri. Se si utilizza BDE per mettere nella 
cache gli aggiornamenti, e possibile collegare esplicitamente i parametri impostando 
la proprieta DataSet dell'oggetto update e poi chiamando il suo metodo SetParams. 
Quando si utilizza un dataset client per memorizzare nella cache gli aggiornamenti, e 
necessario fornire i parametri al relativo oggetto query gestito da TUpdateSQL. Per 
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informazioni, consultare "Utilizzo della proprieta Query di un componente update" 
a pagina 24-49. 

Se la proprieta UpdateObject del dataset viene usata per associare dataset e oggetto 
update, ExecSQL viene chiamato automaticamente. In questo caso, non si deve 
chiamare ExecSQL in un gestore di evento OnllpdateRecord o BeforellpdateRecord, in 
quanto si avrebbe un secondo tentativo di applicare raggiornamento al record attivo. 

I gestori di evento OnllpdateRecord e BeforellpdateRecord indicano il tipo di 
aggiornamento da applicare con un parametro UpdateKind di tipo TUpdateKind. II 
parametro va passato al metodo ExecSQL per indicare quali istruzioni SQL utilizzare. 

II seguente codice lo illustra utilizzando un gestore di evento BeforellpdateRecord: 

void __fastcall TForral : :BDEClientDataSetlBeforeUpdateRecord(TObject *Sender, 

TDataSet *SourceDS, TCustomClientDataSet *DeltaDS, TUpdateKind UpdateKind, bool ^Applied) 

{ 

TDBDataSet *pSrcDS = dynamic_cast <TDBDataSet MSourceDS) ; 
UpdateSQLl->DatabaseName = pSrcDS->DatabaseName; 
UpdateSQLl->SessionName = pSrcDS->SessionName; 
UpdateSQLl->ExecSQL (UpdateKind) ; 
Applied = true; 

} 

Se durante l'esecuzione del programma di aggiornamento viene sollevata 
un'eccezione, l'esecuzione continua nell'evento OnllpdateError , se questo e definite 

Utilizzo della proprieta Query di un componente update 

La proprieta Query di un componente update consente l'accesso ai componenti query 
che implementano le sue istruzioni DeleteSQL, InsertSQL e ModifySQL. Nella maggior 
parte delle applicazioni, non e necessario accedere direttamente a questi componenti 
query. Si specificano le istruzioni che le query eseguono chiamando il metodo Apply 
o ExecSQL dell'oggetto update, mediante le proprieta DeleteSQL, InsertSQL e 
ModifySQL. In certi casi pero e necessario manipolare direttamente un componente 
query. In particolare, la proprieta Query e utile quando si desidera fornire i valori dei 
parametri nelle istruzioni SQL, invece di affidarsi al collegamento automatico dei 
parametri dell'oggetto update ai valori vecchi e nuovi del campo. 

La proprieta Query e accessibile solo in fase di esecuzione. 

La proprieta Query e associata a indice su un valore di TUpdateKind: 

• L'utilizzo di un indice di ukModify permette di accedere alia query che aggiorna 
record esistenti. 

• L'utilizzo di un indice di uklnsert permette di accedere alia query che inserisce 
nuovi record. 

• L'utilizzo di un indice di ukDelete permette di accedere alia query che cancella 
record. 

Quanto segue mostra come utilizzare la proprieta Query per fornire valori del 
parametro che non possono essere collegati automaticamente: 

void __fastcall TForral : :BDEClientDataSetlBeforeUpdateRecord(TObject *Sender, 

TDataSet *SourceDS, TCustomClientDataSet *DeltaDS, TUpdateKind UpdateKind, bool &Applied) 

{ 

UpdateSQLl->DataSet = DeltaDS; // required for the automatic parameter substitution 
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TQuery *pQuery = UpdateSQLl->Query [UpdateKind] ; // access the query 
// make sure the query has the correct DatabaseName and SessionName 
TDBDataSet *pSrcDS = dynamic_cast<TDBDataSet *> (SourceDS) ; 
pQuery->DatabaseNarae = pSrcDS->DatabaseName; 
pQuery->SessionName = pSrcDS->SessionName; 
// now substitute values for custom parameters 
pQuery->ParamByName("TimeOfLastUpdate")->Value = Now(); 
UpdateSQLl->Apply (UpdateKind) ; // now do automatic substitution and execute 
Applied = true; 

} 

Utilizzo di TBatchMove 



TBatchMove incorpora alcune funzioni del Borland Database Engine (BDE) che 
consentono di duplicare un dataset, di aggiungere a un dataset record presi da un 
altro, di aggiornare i record di un dataset con record presi da un altro dataset e di 
cancellare da un dataset record corrispondenti a record di un altro dataset. 
TBatchMove viene usato principalmente per: 

• Trasferire dati da un server a un datasource locale per analizzarli o per svolgere 
altre operazioni. 

• Spostare un database desktop in tabelle su un server remoto come parte di 
un'operazione di upsizing. 

Un componente batch move puo creare sulla destinazione tabelle corrispondenti alle 
tabelle sorgente, mappando automaticamente i nomi di colonna e i tipi di dati, 
secondo quanto opportune 

Creazione di un componente batch move 



Per creare un componente batch move: 

1 Mettere su una scheda o in un modulo dati un componente tabella o query per il 
dataset da cui si vogliono importare record (chiamato dataset Source). 

2 Mettere nella scheda o nel modulo dati il dataset dove si vogliono spostare i record 
(chiamato dataset Destination). 

3 Mettere nel modulo dati o nella scheda un componente TBatchMove prendendolo 
dalla pagina BDE della Component palette e dare alia sua proprieta Name un 
valore univoco, appropriate all'applicazione. 

4 Impostare la proprieta Source del componente batch move al nome della tabella 
dove copiare, aggiungere o aggiornare i record. E possibile selezionare le tabelle 
desiderate nella lista a discesa dei componenti dataset disponibili. 

5 Impostare la proprieta Destination del dataset dove creare, aggiungere a o 
aggiornare. Si puo selezionare una tabella di destinazione nella lista a discesa dei 
componenti dataset disponibili. 
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• In caso di aggiunta, aggiornamento o cancellazione, Destination deve essere una 
tabella di database esistente. 

• Se si vuole copiare una tabella e Destination e una tabella esistente, eseguendo lo 
spostamento batch vengono sovrascritti tutti i dati correnti nella tabella di 
destinazione. 

• Se si crea una tabella nuova copiando una tabella esistente, il nome della tabella 
risultante e quello specificato dalla proprieta Name del componente tabella dal 
quale si copia. II tipo di struttura della tabella risultante sara appropriato al 
server specificato dalla proprieta DatabaseName. 

6 Impostare la proprieta Mode per indicare il tipo di operazione da svolgere. Le 
operazioni valide sono batAppend (l'impostazione predefinita), batUpdate, 
batAppendllpdate, batCopy e batDelete. Per informazioni su questi modi, consul tare 
"Specifica della modalita di un componente batch move" a pagina 24-51. 

7 Facoltativamente, impostare la proprieta Transliterate. Se Transliterate e true 
(l'impostazione predefinita), i dati di tipo carattere sono tradotti dal set di caratteri 
del dataset Source al set di caratteri del dataset Destination, secondo quanto 
opportuno. 

8 Facoltativamente, impostare le mappature di colonna utilizzando la proprieta 
Mappings. Non e necessario impostare la proprieta se si desidera che nello 
spostamento batch la corrispondenza tra le colonne sia basata sulla rispettiva 
posizione nelle tabelle di origine e di destinazione. Per ulteriori informazioni sulla 
mappatura delle colonne, vedere "Mappatura dei tipi di dati" a pagina 24-53. 

9 Facoltativamente, specificare le proprieta ChangedTableName, KeyViolTableName e 
ProblemTableName. Durante lo spostamento batch i record che creano problemi 
incontrati nel corso dell'operazione vengono messi nella tabella specificata da 
ProblemTableName. Quando si aggiorna una tabella Paradox mediante uno 
spostamento batch, le violazioni di chiave si possono segnalare nella tabella 
specificata in KeyViolTableName. ChangedTableName elenca tutti i record che sono 
cambiati nella tabella di destinazione come conseguenza dell'operazione di 
spostamento batch. Non specificando queste proprieta , le tabelle di errore non 
vengono create ne utilizzate. Per ulteriori informazioni sulla gestione di errori di 
spostamento batch, consultare "Gestione degli errori delle operazioni batch move" 
a pagina 24-54. 

Specifica della modalita di un componente batch move 



La proprieta Mode specifica l'operazione che un componente batch move esegue: 



Aggiunge record alia tabella di destinazione. 

Aggiorna i record nella tabella di destinazione con record corrispondenti 
presi nella tabella di origine. L'aggiornamento si basa sull'indice ativo della 
tabella di destinazione. 



Tabella 24.8 Modalita di un componente batch move 
Proprieta Scopo 

batAppend 
batUpdate 
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Tabella 24.8 Modalita di un componente batch move (continua) 
Proprieta Scopo 

batAppendUpdate Se nella tabella di destinazione esiste un record corrispondente, lo aggiorna. 
Altrimenti, aggiunge i record nella tabella di destinazione. 

batCopy Crea la tabella di destinazione in base alia struttura della tabella di origine. 

Se la tabella di destinazione esiste gia , viene accantonata e ricreata. 

batDelete Cancella nella tabella di destinazione i record corrispondenti ai record nella 

tabella di origine. 

Aggiunta di record 

Per l'aggiunta di dati, il dataset di destinazione deve rappresentare una tabella 
esistente. Durante l'operazione di aggiunta, BDE converte i dati per adeguarli ai tipi e 
alle dimensioni del dataset di destinazione, se necessario. Se la conversione non e 
possibile, viene sollevata un'eccezione e i dati non vengono aggiunti. 

Aggiornamento di record 

Per l'aggiornamento dei dati, il dataset di destinazione deve rappresentare una 
tabella esistente e deve avere un indice definito che consenta il confronto dei record. 
Se per il confronto sono usati i campi indice primari, i record che nel dataset di 
destinazione hanno campi indice corrispondenti ai campi indice dei record nel 
dataset di origine vengono riscritti con i dati del dataset di origine. Durante 
l'operazione di aggiornamento, BDE converte i dati per adeguarli ai tipi e alle 
dimensioni del dataset di destinazione, se necessario. 

Aggiunta e aggiornamento di record 

Per aggiungere e aggiornare dati, il dataset di destinazione deve rappresentare una 
tabella esistente e deve avere un indice definito che consenta di confrontare i record. 
Se per il confronto si utilizzano i campi dell'indice principale, i record che nel dataset 
destinazione hanno campi indice corrispondenti ai record del dataset di origine 
vengono sovrascritti con i dati del dataset sorgente. In caso contrario, al dataset 
destinazione vengono aggiunti i dati presi dal dataset sorgente. Durante l'operazione 
di aggiunta e di aggiornamento, BDE converte i dati per adeguarli ai tipi e alle 
dimensioni del dataset di destinazione, se necessario. 

Copia di dataset 

Per copiare un dataset sorgente, il dataset di destinazione non deve rappresentare 
una tabella esistente. In caso contrario, l'operazione di spostamento batch sovrascrive 
la tabella esistente con una copia del dataset di origine. 

Se i dataset di origine e di destinazione sono gestiti da motori di database di tipo 
diverso, (per esempio, Paradox e InterBase), BDE crea a destinazione un dataset la cui 
struttura e quanto piu possibile simile a quella del dataset sorgente ed esegue 
automaticamente le conversioni di tipo e di dimensione dei dati, secondo quanto 
necessario. 
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TBatchMove non copia strutture di metadati come indici, vincoli e procedure 
registrate. E necessario ricreare questi oggetti di metadati sul server di database, o 
attraverso lo SQL Explorer, secondo quanta necessario. 

Cancellazione di record 

Per cancellare dati nel dataset di destinazione, questo deve rappresentare una tabella 
esistente e deve avere un indice definito che consenta il confronto dei record. Se per il 
confronto si usano i campi dell'indice principale, i record i cui campi indice nel 
dataset destinazione corrispondono ai campi indice dei record nel dataset sorgente 
vengono cancellati nella tabella di destinazione. 



Mappatura dei tipi di dati 



In modalita bat Append, un componente batch move crea la tabella di destinazione in 
base ai tipi di dati della colonna della tabella di origine. Le colonne e i tipi vengono 
confrontati in base alia rispettiva posizione nelle tabelle di origine e di destinazione. 
In altre parole, la prima colonna della sorgente viene fatta corrispondere con la prima 
colonna della destinazione, e cosi via. 

Per ridefinire le mappature di colonna predefinite, si ricorre alia proprieta Mappings. 
Mappings e una lista di mappature di colonna (una per riga) che puo assumere due 
forme. Per mappare una colonna della tabella sorgente con una colonna dallo stesso 
nome nella tabella di destinazione, si puo usare un listato semplice che specifica il 
nome della colonna da far corrispondere. Ad esempio, la seguente mappatura 
specifica che una colonna chiamata ColName nella tabella sorgente va fatta 
corrispondere con una colonna dello stesso nome nella tabella di destinazione: 

ColName 

Per fare corrispondere una colonna chiamata SourceColName nella tabella sorgente 
con una colonna chiamata DestColName nella tabella di destinazione, la sintassi e : 

DestColName = SourceColName 

Se i tipi di dati della colonna sorgente e di destinazione non sono uguali, l'operazione 
di spostamento batch prova ad applicare la "migliore delle corrispondenze". Tronca i 
dati di tipo carattere, se necessario, e tenta un po' di conversione, se possibile. (Ad 
esempio, mappando una colonna CHAR(IO) verso una colonna CHAR(5) tronchera 
gli ultimi cinque caratteri della colonna sorgente. 

Come esempio di conversione, se una colonna sorgente di dati di tipo carattere viene 
fatta corrispondere con una colonna di destinazione di tipo integer, l'operazione di 
spostamento batch converte il carattere '5 ' nel corrispondente valore integer. Valori 
che non possono essere convertiti generano errori. Per ulteriori informazioni sugli 
errori, consultare "Gestione degli errori delle operazioni batch move" a pagina 24-54. 

Quando sposta dati fra tabelle di tipo diverso, un componente batch move traduce 
opportunamente i tipi di dati in base al tipo di server del dataset. Per conoscere le piu 
recenti tabelle di mappatura tra i vati tipi server, consultare la guida BDE in linea. 

Per gli spostamenti batch verso server di database SQL, bisogna avere il server di 
database in questione e una versione di C++Builder sulla quale sia installato lo SQL 
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Link appropriato, oppure si puo usare ODBC, se si dispone degli opportuni driver 
ODBC. 

Esecuzione di un'operazione batch move 



In fase di esecuzione, per eseguire un'operazione batch precedentemente preparata si 
utilizza il metodo Execute. Ad esempio, se BatchMoveAdd e il nome di un componente 
batch move, la seguente istruzione lo esegue: 

BatchMoveAdd->Execute ( ) ; 

Si puo anche eseguire uno spostamento batch in fase di progettazione facendo clic 
con il pulsante destro su un componente batch move e poi selezionando Execute nel 
menu di scelta rapida. 

Negli spostamenti batch, la proprieta MovedCount conteggia il numero di record 
spostati. 

La proprieta RecordCount specifica il numero massimo di record da spostare. Se 
RecordCount e nullo, tutti i record vengono spostati, iniziando con il primo record nel 
dataset sorgente. Se RecordCount e un numero positivo, vengono spostati i record fino 
a un massimo di RecordCount, iniziando dal record attivo nel dataset sorgente. Se 
RecordCount e maggiore del numero di record tra il record attivo nel dataset sorgente 
e il suo ultimo record, lo spostamento batch termina quando si raggiunge la fine del 
dataset sorgente. E possibile esaminare MoveCount per determinare quanti record 
sono stati effettivamente trasferiti. 

Gestione degli errori delle operazioni batch move 



Due tipi di errori possono verificarsi nelle operazioni batch move: gli errori di 
conversione del tipo di dati e le violazioni di integrita . TBatchMove ha diverse 
proprieta per rilevare e gestire gli errori. 

La proprieta AbortOnProblem specifica se l'operazione va interrotta quando si verifica 
un errore di conversione di tipo dati. Se AbortOnProblem e true, l'operazione batch 
move viene annullata quando si verifica un errore. Se false, l'operazione continua. E 
possibile esaminare la tabella che si specifica in ProblemTableName per determinare 
quali record hanno causato problemi. 

La proprieta AbortOnKeyViol indica se l'operazione va interrotta quando si verifica 
una violazione di chiave Paradox. 

La proprieta ProblemCount indica il numero di record che non hanno potuto essere 
gestiti nella tabella di destinazione senza perdite di dati. Se AbortOnProblem e true, 
questo numero e uno, poiche l'operazione viene interrotta non appena si verifica un 
errore. 

Le seguenti proprieta permettono a un componente batch move di creare tabelle 
aggiuntive che documentano l'operazione di spostamento batch: 
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• ChangedTableName, se specificato, crea una tabella locale Paradox contenente tutti i 
record nella tabella di destinazione che sono cambiati a seguito di un'operazione 
di aggiornamento o di cancellazione. 

• KeyViolTableName, se specificato, crea una tabella locale Paradox che contiene tutti 
i record dalla tabella sorgente che hanno determinato una violazione di chiave 
quando lavoravano con una tabella Paradox. Se AbortOnKeyViol e true, la tabella 
conterra al massimo un voce poiche l'operazione viene interrotta al primo 
problema incontrato. 

• ProblemTableName, se specificato, crea una tabella locale Paradox contenente tutti i 
record che non e stato possibile registrare nella tabella di destinazione a causa di 
errori di conversione del tipo dati. Ad esempio, la tabella potrebbe contenere i 
record dalla tabella di sorgente contenenti dati che, per essere inseriti nella tabella 
di destinazione, dovevano essere troncati. Se AbortOnProblem e true, la tabella 
contiene al massimo un record poiche l'operazione e stata interrotta al primo 
problema incontrato. 

Non specificando ProblemTableName, i dati nel record vengono troncati e inseriti nella 
tabella di destinazione. 



II Data Dictionary 



Quando si utilizza BDE per accedere ai dati, l'applicazione ha accesso al Data 
Dictionary. II Data Dictionary mette a disposizione un'area di memoria 
personalizzabile, indipendente dalle applicazioni, dove e possibile creare set di 
attributi di campi estesi che descrivono il contenuto e l'aspetto dei dati. 

Ad esempio, se si sviluppano frequentemente applicazioni finanziarie, e possibile 
creare un certo numero di set speciali di attributi di campo che descrivono vari 
formati di visualizzazione delle valute. Quando i dataset dell'applicazione vengono 
creati in fase di progetto, invece che impostando manualmente i campi delle valute in 
ciascun dataset, si possono associare i campi in questione a un set esteso di attributi 
di campo nel dizionario dati. L'uso del dizionario dati assicura un aspetto coerente 
dei dati all'interno delle singole applicazioni e tra un'applicazione e l'altra. 

In un ambiente client /server, il Data Dictionary puo risiedere su un server remoto, in 
modo da consentire un'ulteriore condivisione delle informazioni. 

Per imparare in che modo creare set estesi di attributi di campo utilizzando l'editor 
Fields in fase di progettazione, e come associarli ai campi di tutti i dataset di 
un'applicazione, consultare "Creazione di set di attributi per i componenti campo" a 
pagina 23-14. Per saperne di piu sulla creazione di un dizionario dati e degli attributi 
di campo estesi con SQL e con Database Explorers, consultare i relativi file di guida 
in linea. 
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Un'interfaccia di programmazione al Data Dictionary e disponibile nel file header 
drintf (situato nella directory includeWCL). L'interfaccia fornisce i seguenti metodi: 

Tabella 24.9 Interfaccia del Data Dictionary 



Dictionary Active 

Dictionary Deactivate 

IsNullID 

FindDatabaselD 

FindTablelD 

FindFieldID 

FindAttrlD 

GetAttrName 

GetAttrNames 

GetAttrlD 

NewAttr 

UpdateAttr 

CreateField 
UpdateField 

AssociateAttr 

UnassociateAttr 

GetControlClass 

QualifyTableName 

QualifyTableNameByName 

HasConstraints 

UpdateConstraints 

UpdateDataset 



Indica se il dizionario dati e attivo. 

Disattiva il dizionario dati. 

Indica se un certo ID e un ID nullo 

Restituisce l'ID di un database fornendo il suo alias. 

Restituisce l'ID di una tabella in un database specificate 

Restituisce l'ID di un campo in una tabella specificata. 

Restituisce l'ID di un set di attributi dato. 

Restituisce il nome di un set di attributi dato il suo ID. 

Esegue una callback per ogni attributo impostato nel dizionario. 

Restituisce l'ID dell'attributo impostato di un campo specificate 

Crea un nuovo set di attributi da un componente campo. 

Aggiorna un set di attributi corrispondente alle proprieta di un 
campo. 

Crea un componente campo in base agli attributi registrati. 

Modifica le proprieta di un campo per farle corrispondere a un 
set di attributi specificato. 

Associa un set di attributi all'ID specificato di un campo. 

Rimuove un set di attributi dall'ID di un campo. 

Restituisce la classe di controllo dell'ID specificato di un 
attributo. 

Restituisce un nome di tabella per esteso (qualificato dal nome 
utente). 

Restituisce un nome della tabella per esteso (qualificato dal nome 
utente). 

Indica se il dataset ha vincoli nel dizionario. 
Aggiorna i vincoli importati di un dataset. 

Aggiorna un dataset secondo le impostazioni e i vincoli attivi nel 
dizionario. 



Strumenti per operare con BDE 



Uno dei vantaggi di usare BDE come meccanismo di accesso di dati e la ricchezza di 
programmi di utilita di cui C++Builder dispone. Questi programmi di utilita 
comprendono: 

• SQL Explorer e Database Explorer: C++Builder viene fornito con una di queste 
due applicazioni, a seconda della versione acquistata. Entrambi consentono di 

• Esaminare le tabelle e le strutture di database esistenti. SQL Explorer permette 
di esaminare e di eseguire query su database SQL remoti. 
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• Riempire tabelle di dati 

• Creare set estesi di attributi di campo nel Data Dictionary o associarli ai campi 
di un'applicazione. 

• Creare e gestire alias BDE. 
SQL Explorer consente inoltre di: 

• Creare oggetti SQL, come procedure registrate su server di database remoti. 

• Visualizzare il testo ricostruito di oggetti SQL su server di database remoti. 

• Eseguire procedure SQL. 

• SQL Monitor: SQL Monitor permette di tenere sotto controllo le comunicazioni 
fra il server di database remoto e BDE. Si possono filtrare i messaggi che si 
desidera guardare, limitandoli solo alle categorie che interessano. SQL Monitor e 
molto utile in fase di debug delle applicazioni. 

• Programma di utilita BDE Administration: II programma di utilita BDE 
Administration permette di aggiungere nuovi driver di database, di configurare le 
impostazioni predefinite dei driver esistenti e di creare nuovi alias BDE. 

• Database Desktop: Se si utilizzano tabelle Paradox o dBASE, Database Desktop 
permette di visualizzare e di modificare i dati, di creare nuove tabelle e di 
ristrutturare le tabelle esistenti. II controllo consentito da Database Desktop e 
migliore di quello ottenuto utilizzando i metodi di un componente TTable (ad 
esempio, permette di specif icare i controlli di validita e i driver di linguaggio). 
Inoltre, fornisce l'unico meccanismo per ristrutturare le tabelle Paradox e dBASE 
che non sia quello di fare chiamate dirette alia API di BDE. 
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Capitolo 




Operazioni con componenti ADO 

I componenti dbGo forniscono l'accesso ai dati tramite il framework ADO. ADO 
(acronimo di ActiveX Data Objects di Microsoft), e una serie di oggetti COM che 
consentono l'accesso ai dati tramite un DB provider OLE. I componenti dbGo 
incapsulano questi oggetti ADO nell'architettura di database C++Builder. 

Nelle applicazioni basate su ADO, lo strato ADO e formato da Microsoft ADO 2.1, da 
un DB provider OLE o da un driver ODBC per l'accesso al datastore, dal software 
client per lo specif ico sistema di database utilizzato (nel caso di database SQL), da un 
sistema di database back-end (per sistemi di database SQL) e da un database. Perche 
l'applicazione sia completamente funzionale, tutti questi sistemi devono essere 
accessibili all'applicazione basata su ADO. 

Gli oggetti ADO piu importanti sono gli oggetti Connection, Command e Recordset. 
Questi oggetti ADO sono rappresentati dai componenti TADOConnection, 
TADOCommand, e dai componenti ADO dataset. II framework ADO include altri 
oggetti "helper", come gli oggetti Field e Properties, ma solitamente non sono 
utilizzati in modo diretto nelle applicazioni dbGo e non sono inglobati in componenti 
dedicati. 

Questo capitolo presenta i componenti dbGo e discute le funzionalita esclusive che 
essi introducono nella comune architettura database di C++Builder. Prima di 
affrontare le funzionalita caratteristiche dei componenti dbGo, e bene imparare a 
conoscere le funzionalita comuni dei componenti connection di database e dei 
dataset descritti nel capitolo Capitolo 21, "Connessione ai database" e nel Capitolo 
22, "I dataset." 

Panoramica dei componenti ADO 



La pagina ADO page della Component palette contiene i componenti dbGo. Questi 
componenti consentono ai programmatori di connettersi ad un datastore ADO e 
quindi di eseguire comandi e recuperare dati dalle tabelle nel database utilizzando il 
framework ADO. Sul computer host deve essere installato ADO 2.1 (o una versione 
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successiva). Inoltre, deve essere installato un software client per il sistema di 
database di destinazione (come Microsoft SQL Server), oltre ad un driver OLE DB o 
un driver ODBC specifico per quel particolare sistema di database. 

La maggior parte dei componenti dbGo hanno delle controparti dirette nei 
componenti disponibili per altri meccanismi di accesso ai dati: un componente 
connection di database (TADOConnection) e diversi tipi di dataset. Inoltre, dbGo 
include TADOCommand, un componente semplice che non e un dataset ma che 
rappresenta un comando SQL da eseguire sul datastore ADO. 

In tabella sono elencati i componenti ADO. 



Tabella 25.1 Componenti ADO 



Componente 


Uso 


TADOConnection 


Un componente database connection per stabilire una connessione con 
un datastore ADO; piu componenti dataset e command di ADO possono 
condividere questa connessione per eseguire comandi, recuperare dati e 
operare sui metadati. 


TADODataSet 


11 dataset primario utilizzato per reperire e operare sui dati; 
TADODataSet puo recuperare dati da una o piu tabelle; puo connettersi 
a un datastore in modo diretto oppure tramite un componente 
TADOConnection. 


TADOTable 


Un dataset di tipo tabella per reperire e operare su un recordset prodotto 
da una singola tabella di database; TADOTable puo connettersi a un 
datastore in modo diretto oppure tramite un componente 
TADOConnection. 


TADOQuery 


Un dataset di tipo query per reperire e operare su un recordset prodotto 
da un'istruzione SQL valida; TADOQuery puo eseguire anche istruzioni 
SQL DDL (data definition language). Puo connettersi a un datastore in 
modo diretto o tramite un componente TADOConnection 


TADOStoredProc 


Un dataset di tipo procedura registrata per eseguire procedure 
registrate; TADOStoredProc esegue procedure registrate che recuperano 
o non recuperano dati. Puo connettersi a un datastore in modo diretto o 
tramite un componente TADOConnection. 


TADOCommand 


Un semplice componente per eseguire comandi (istruzioni SQL che non 
restituiscono set di risultati); TADOCommand puo essere utilizzato con 
un componente dataset di supporto, o recuperare un dataset da una 
tabella; puo connettersi a un datastore in modo diretto o tramite un 
componente TADOConnection. 



Connessione a datastore ADO 



Le applicazioni dbGo utilizzano ActiveX Data Objects (ADO) 2.1 di Microsoft per 
interagire con un provider OLE DB che si collega a un datastore e accede ai suoi dati. 
Uno degli elementi che un datastore puo rappresentare e un database. 
Un'applicazione basata su ADO richiede l'installazione di ADO 2.1 sul computer 
client. ADO e OLE DB sono forniti da Microsoft e sono installati con Windows. 

Un provider ADO e uno dei vari tipi possibili di accesso, dai driver nativi OLE DB ai 
driver ODBC. Questi driver devono essere installati sul computer client. I driver OLE 
DB dei diversi sistemi di database sono forniti dal produttore del database o da terzi. 
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Se l'applicazione utilizza un database SQL, come Microsoft SQL Server o Oracle, il 
software client del sistema di database deve essere installato anche sul computer 
client. II software client e fornito dal produttore del database e viene installato dal 
CD (o dal disco) del sistema di database). 

Per collegare l'applicazione al datastore, si utilizza un componente connection ADO 
(TADOConnection), che va configurato per l'impiego di uno dei provider ADO 
disponibili. Configurare il componente ADO connection in modo che utilizzi uno dei 
provider ADO disponibili. Benche TADOConnection non sia strettamente necessario, 
dato che il comando e i componenti dataset ADO possono connettersi utilizzando 
direttamente la tloro proprieta ConnectionString, e possibile utilizzarlo per 
condividere una sola connessione tra piu componenti ADO. In questo modo, si pud 
ridurre la quantita di risorse utilizzate e si ha la possibility di creare transazioni che 
attraversano piu dataset. 

Come altri componenti di connessione ai database, TADOConnection supporta queste 
funzioni 

• Controllo delle connessioni 

• Controllo del login al server 

• Gestione delle transazioni 

• Operazioni con i dataset associati 

• Invio di comandi al server 

• Ottenimento di metadati 

Oltre a queste funzionalita , comuni a tutti i componenti di connessione ai database, 
TADOConnection supporta 

• Un'ampia gamma di opzioni utilizzabili per la messa a punto della connessione. 

• La capacita di elencare gli oggetti command che utilizzano la connessione. 

• Eventi ulteriori quando vengono eseguite operazioni comuni. 

Connessione a un datastore mediante TADOConnection 



Uno o piu componenti dataset e comandi ADO possono condividere una singola 
connessione a un datastore mediante l'utilizzo di TADOConnection. A questo scopo i 
componenti dataset e comandi vengono associati al componente connessione 
mediante le rispettive proprieta Connection. In fase di progetto, selezionare 
nell'Object Inspector il componente connessione desiderato dall'elenco a discesa 
della proprieta Connection. In fase di esecuzione, assegnare il riferimento alia 
proprieta Connection. Per esempio, il comando seguente associa un componente 
TADODataSet con un componente TADOConnection. 

ADODataSetl->Connection = ADOConnectionl; 

II componente connection rappresenta un oggetto di connessione ADO. Prima di 
poterlo utilizzare per stabilire una connessione, e necessario identificare il datastore a 
cui ci si vuole collegare. Di solito, si forniscono informazioni mediante la proprieta 
ConnectionString, una stringa delimitata da punto e virgola che elenca uno o piu 
parametri di connessione indicati con nome. ConnectionString e una stringa separata 
con punti e virgola che elenca uno o piu parametri di connessione con nome. Questi 
parametri identificano il datastore specificando o il nome di un file contenente le 
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informazioni di connessione, o il nome di un provider ADO e un riferimento che 
identifica il datastore. Per fornire le informazioni, si utilizzano i seguenti i nomi 
predefiniti di parametro: 

Parametro Descrizione 

Provider Nome del provider locale ADO da utilizzare per la connessione. 

Data Source Nome del datastore. 

File name Nome del file contenente informazioni di connessione. 

Remote Provider Nome del provider ADO residente su una macchina remota. 

Remote Server Nome del server remoto quando si utilizza un provider remote 

Cosi, un valore tipico di ConnectionString si presenta in questo modo 

Provider=MSDASQL . 1 ; Data Source=MQIS 

I parametri di connessione di ConnectionString non devono obbligatoriamente 
includere il parametro Provider, o Remote Provider, se il provider ADO viene 
specificato utilizzando la proprieta Provider. Analogamente, non bisogna specificare 
il parametro Data Source se si utilizza la proprieta DefaultDatabase. 

Inoltre, ai parametri elencati, ConnectionString puo aggiungere particolari parametri 
di connessione richiesti dallo specifico provider ADO utilizzato. Questi parametri di 
connessione aggiuntivi possono includere l'ID utente e la password, se si preferisce 
immettere mediante codice le informazioni di login. 

In progettazione, e possibile utilizzare il Connection String Editor per generare una 
stringa di connessione selezionando da elenchi gli elementi della connessione (come 
il provider e il server). Fare clic nell'Object Inspector sul pulsante ellissi della 
proprieta ConnectionString per attivare il Connection String Editor, che e un editor di 
proprieta ActiveX fornito da ADO. 

Una volta specificata la proprieta ConnectionString (e, facoltativamente, la proprieta 
Provider), si puo utilizzare il componente connection ADO per connettersi al 
datastore ADO o scollegarsi, sebbene in certi casi si preferisca prima utilizzare altre 
proprieta per mettere a punto la connessione. Quando si collega o si scollega dal 
datastore, TADOConnection permette di rispondere ad alcuni eventi ulteriori, oltre 
quelli comuni a tutti i componenti connection database. Questi eventi aggiuntivi 
sono descritti in "Eventi alio stabilirsi di una connessione" a pagina 25-8 e "Eventi 
alia chiusura del collegamento" a pagina 25-8. 

Se non si attiva esplicitamente la connessione impostando a true la proprieta 
Connected del componente connessione, l'attivazione awerra automaticamente non 
appena si attivera il primo componente dataset oppure si eseguira per la prima volta 
un comando usando un componente comandi ADO. 

Accesso all'oggetto connessione 

Utilizzare la proprieta ConnectionObject di TADOConnection per accedere 
direttamente all'oggetto connessione ADO sottostante. Utilizzando questo 
riferimento, e possibile accedere alle proprieta e chiamare i metodi dell'oggetto ADO 
Connection sottostante. 
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L'uso dell'oggetto ADO Connection sottostante richiede una buona conoscenza 
operativa degli oggetti ADO in generale e delloggetto ADO Connection in particolare. 
Non si consiglia l'utilizzo dell'oggetto Connection a meno che non si abbia familiarita 
con le operazioni con gli oggetti Connection. Per informazioni specifiche sull'utilizzo 
degli oggetti Connection ADO, consultare la Guida di Microsoft Data Access SDK. 

Messa a punto di una connessione 



Uno dei vantaggi dell'impiego di TADOConnection per stabilire una connessione con 
un datastore, invece di fornire semplicemente una stringa di connessione per i 
componenti di comando e dataset ADO, e che TADOConnection consente di 
controllare molto efficacemente le condizioni e gli attributi della connessione. 

Come forzare connessioni asincrone 

Utilizzare la proprieta ConnectOptions per forzare una connessione asincrona. Le 
connessioni asincrone permettono a un'applicazione di continuare l'elaborazione 
senza attendere che la connessione sia aperta completamente. 

Per impostazione predefinita, ConnectionOptions e impostata a coConnectUnspecified 
che consente al server di decidere il miglior tipo di connessione. Per rendere 
asincrona la connessione in modo esplicito, impostare ConnectOptions a 
coAsyncConnect. 

Le routine di esempio riportate di seguito attivano e disattivano le connessioni 
asincrone nel componente connessione specificato: 

void __fastcall TForml : :AsyncConnectButtonClick(TObject *Sender) 

{ 

ADOConnectionl->Close() ; 

ADOConnectionl->ConnectOptions = coAsyncConnect; 
ADOConnectionl->Open ( ) ; 

} 

void __fastcall TForml: :ServerChoiceConnectButtonClick(TObject *Sender) 

{ 

ADOConnectionl->Close ( ) ; 

ADOConnectionl->ConnectOptions = coConnectUnspecified; 
ADOConnectionl->Open ( ) ; 

} 

Controllo dei timeout 

Le proprieta Connection! Imeout e CommandTimeout consentono di controllare il 
periodo di tempo che deve trascorrere prima che eventuali tentativi di comando o di 
connessione siano considerati come non andati a buon fine e quindi annullati. 

Connection! imeout specifica il periodo di tempo, in secondi, che deve trascorrere 
prima che un tentativo di connessione al datastore sia considerato come non riuscito. 
Se la connessione, non viene portata a termine con successo prima della scadenza del 
periodo di tempo specificato in Connection! imeout, il tentativo di connessione viene 
annullato: 

ADOConnectionl->ConnectionTimeout = 10; // seconds 
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ADOConnectionl->Open ( ) ; 

CommandTimeout specifica il periodo di tempo, in secondi, che deve trascorrere prima 
che un tentativo di comando sia considerato come non riuscito. Se il comando, 
iniziato da una chiamata al metodo Execute non e stato portato a termine con successo 
prima della scadenza del periodo di tempo specificato in CommandTimeout, il 
comando viene annullato e ADO genera un'eccezione: 

ADOConnectionl->ConnectionTimeout = 10; 

ADOConnectionl->Execute("DROP TABLE Employeel997", cmdText, TExecuteOptions ( ) ) ; 

Indicazione dei tipi di operazione che la connessione supporta 

Le connessioni ADO vengono stabilite utilizzando una modalita specifica, simile a 
quella utilizzata quando si apre un file. La modalita di connessione determina le 
autorizzazioni di cui la connessione dispone e percio i tipi di operazione (come 
lettura e scrittura) effettuabili. 

Utilizzare la proprieta Mode per indicare la modalita di connessione. I valori possibili 
sono elencati nella Tabella 25.2: 

Tabella 25.2 Modalita di connessione ADO 

Modalita di 

connessione Significato 

cmUnknown Le autorizzazioni della connessione non sono ancora impostate o non 

possono essere determinate. 

cmRead La connessione dispone di autorizzazione per sola lettura. 

cmWrite La connessione dispone di autorizzazione per sola scrittura. 

cmReadWrite La connessione dispone di autorizzazione per lettura e scrittura. 

cmShareDenyRead Impedisce ad altri di stabilire la connessione con autorizzazione di lettura. 

cmShareDenyWrite Impedisce ad altri di stabilire la connessione con autorizzazione di 
scrittura. 

cmShareExclusive Impedisce ad altri di stabilire la connessione. 

cmShareDenyNone Impedisce ad altri di stabilire la connessione con qualsiasi autorizzazione. 



I valori possibili di Mode corrispondono ai valori ConnectModeEnum della proprieta 
Mode sull'oggetto di connessione ADO sottostante. Per ulteriori informazioni si 
questi valori, consultare la Guida di Microsoft Data Access SDK. 

Come specificare se la connessione awia in automatico le transazioni 

Utilizzare la proprieta Attributes per controllare la ritenzione da parte del 
componente connessione delle modifiche confermate e di quelle annullate. Se il 
componente connection utilizza la ritenzione delle convalide, ogni volta che 
l'applicazione convalida una transazione, viene avviata automaticamente una nuova 
transazione. Se il componente connection utilizza la ritenzione degli annullamenti, 
ogni volta che l'applicazione annulla la transazione viene avviata automaticamente 
una nuova transazione. 

Attributes e un set che puo contenere una, entrambe o nessuna delle costanti 
xaCommitRetaining e xaAbortRetaining. Quando Attributes contiene 
xaCommitRetaining, la connessione utilizza la ritenzione delle convalide. Quando 
Attributes contiene xaAbortRetaining, utilizza la ritenzione degli annullamenti. 
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Controllare se la ritenzione delle modifiche confermate o di quelle annullate e attiva 
utilizzando il metodo Set Contains. Si attiva la ritenzione delle convalide o degli 
annullamenti aggiungendo il valore appropriate alia proprieta Attributes ; si 
disattivano sottraendo il valore. Le routine di esempio riportate di seguito attivano e 
disattivano la ritenzione delle modifiche in un componente ADO connection. 

void fastcall TForral: :RetainingCommitsOnButtonClick(TObject *Sender) 

{ 

ADOConnectionl->Close() 

if ( ! ADOConnectionl->Attributes .Contains (xaCommitRetaining) ) 

ADOConnectionl->Attributes = TXactAttributes ( ) « xaCommitRetaining; 
ADOConnectionl->Open ( ) 

} 

void __fastcall TForral: :RetainingCommitsOf fButtonClick(TObject *Sender) 

{ 

ADOConnectionl->Close ( ) 

if (ADOConnectionl->Attributes .Contains (xaCommitRetaining) ) 

ADOConnectionl->Attributes = TXactAttributes ( ) » xaCommitRetaining; 
ADOConnectionl->Open ( ) 

} 

Accesso ai comandi della connessione 



Come altri componenti per la connessione ai database, si accede ai dataset associati 
alia connessione mediante le proprieta DataSets e DataSetCount. Tuttavia, dbGo 
include anche oggetti TADOCommand, che non sono dataset, ma che hanno una 
relazione simile con il componente connection. 

E possibile utilizzare le proprieta Commands e CommandCount di TADOConnection per 
accedere agli oggetti di comando ADO associati nello stesso modo in cui si utilizzano 
le proprieta DataSets e DataSetCount per accedere ai dataset associati. A differenza di 
DataSets e DataSetCount, che elencano solo i dataset attivi, Commands e 
CommandCount forniscono riferimenti a tutti i componenti TADOCommand associati 
al componente connessione. 

Commands e un array a base zero di riferimenti a componenti comandi ADO. La 
proprieta CommandCount fornisce un conteggio totale di tutti i comandi elencati in 
Commands. Si possono utilizzare queste proprieta insieme per passare in sequenza 
attraverso tutti i comandi che utilizzano un componente connection, come illustrato 
nel seguente codice: 

for (int i = 0; i < ADOConnection2->CommandCount; i++) 
ADOConnection2->Commands [i] ->Execute ( ) ; 

Eventi di connessione ADO 



Oltre agli eventi soliti, che si verificano per tutti i componenti di connessione ai 
database, TADOConnection genera diversi altri eventi che si verificano durante il 
normale impiego. 
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Eventi alio stabilirsi di una connessione 

Oltre agli eventi BeforeConnect e AfterConnect che sono comuni a tutti i componenti di 
connessione ai database, TADOConnection quando stabilisce una connessione genera 
anche gli eventi OnWillConnect e OnConnectComplete. Questi eventi si verificano dopo 
BeforeConnect. 

• OnWillConnect si verifica prima che il provider ADO stabilisca una connessione. 
Consente di fare le ultime modifiche alia stringa di connessione, fornisce lo 
username e la password se il login viene gestito manualmente, forza una 
connessione asincrona, oppure annulla la connessione prima che sia stabilita. 

• OnConnectComplete si verifica dopo l'apertura della connessione. Siccome 
TADOConnection puo rappresentare le connessioni asincrone, conviene utilizzare 
OnConnectComplete, che entra in gioco dopo che la connessione e aperta o quando 
non va a buon fine a causa di una condizione di errore, invece dell'evento 
AfterConnect, che entra in gioco dopo che il componente connection ha incaricato il 
provider ADO di stabilire la connessione, ma non necessariamente dopo che la 
connessione e stata aperta. 

Eventi alia chiusura del collegamento 

Oltre agli eventi BeforeDisconnect e After Disconnect, comuni a tutti i componenti di 
connessione ai database, TADOConnection dopo avere chiuso una connessione 
genera anche un evento OnDisconnect. OnDisconnect entra in azione dopo che la 
connessione e stata chiusa, ma prima che vengano chiusi i dataset associati e prima 
dell'evento AfterDisconnect. 

Eventi durante la gestione delle transazioni 

II componente connessione di ADO possiede una serie di eventi che consentono di 
determinare se sono stati completati i processi correlati alia transazione. Questi 
eventi indicano al datastore quando un processo di transazione, iniziato da un 
metodo BeginTrans, CommitTrans e RollbackTrans, e stato portato a termine con 
successo. 

• L'evento OnBeginTransComplete si verifica non appena il datastore ha iniziato con 
successo una transazione, in conseguenza di una chiamata al metodo BeginTrans. 

• L'evento di OnCommitTransComplete si verifica dopo che una transazione e stata 
confermata con successo, in conseguenza ad una chiamata al metodo 
CommitTrans. 

• L'evento OnRollbackTransComplete si verifica dopo che una transazione e stata 
annullata con successo, in conseguenza ad una chiamata al metodo RollbackTrans. 

Altri eventi 

I componenti connection ADO introducono altri due eventi utilizzabili per 
rispondere alle notifiche provenienti dall'oggetto di connessione ADO sottostante: 

• L'evento OnExecuteComplete si verifica dopo che il componente connection ha 
eseguito un comando sul datastore (ad esempio, dopo avere chiamato il metodo 
Execute). OnExecuteComplete indica se l'esecuzione ha avuto successo. 
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• L'evento OnlnfoMessage entra in azione quando l'oggetto connection sottostante 
fornisce informazioni dettagliate, dopo il completamento di un'operazione. II 
gestore di evento OnlnfoMessage riceve l'interfaccia verso un oggetto ADO Error 
contenente le informazioni dettagliate e un codice di stato che segnala se 
l'operazione e andata a buon fine. 

Uso di dataset ADO 



I componenti dataset ADO incapsulano l'oggetto ADO Recordset. Ereditano le 
funzionalita di dataset comuni, descritte nel Capitolo 22, "I dataset", e le 
implementano tramite ADO. Per utilizzare un dataset ADO, e necessario prendere 
familiarita con queste funzioni comuni. 

Alle funzioni di dataset comuni, tutti i dataset ADO aggiungono proprieta , eventi e 
metodi per 

• II collegamento a un datastore ADO. 

• L'accesso all'oggetto Recordset sottostante. 

• Filtraggio dei record in base a segnalibri. 

• Ottenimento di record in modo asincrono. 

• Esecuzione aggiornamenti batch (uso degli aggiornamenti in cache). 

• Utilizzo di file su disco per memorizzare dati. 

Ci sono quattro dataset ADO: 

• TADOTable, un dataset di tipo tabella che rappresenta tutte le righe e le colonne di 
una singola tabella di database. Per informazioni sull'utilizzo di TADOTable e di 
altri dataset di tipo tabella, consultare "Utilizzo dei dataset di tipo tabella" a 
pagina 22-26. 

• TADOQuery, un dataset di tipo query che incorpora un'istruzione SQL e permette 
alle applicazioni di accedere ai record risultanti, se esistono. Per informazioni 
sull'utilizzo di dataset di tipo TADOquery e di altri di tipo query, vedere "Utilizzo 
di dataset di tipo query" a pagina 22-43. 

• TADOStoredProc, un dataset di tipo procedura registrata, che esegue una 
procedura registrata definita su un server di database. Per informazioni 
sull'utilizzo di TADOStoredProc e di altri dataset di tipo procedura registrata, 
consultare "Utilizzo di dataset di tipo procedura registrata" a pagina 22-52. 

• TADODataSet, un dataset generico che incorpora le funzionalita degli altri tre tipi. 
Per una descrizione delle funzioni particolari di TADODataSet, consultare 
"Utilizzo di TADODataSet" a pagina 25-16. 

Quando ADO viene utilizzato per accedere a informazioni di database, non e 
necessario utilizzare un dataset come TADOQuery per rappresentare comandi SQL 
che non restituiscono un cursor. Invece, e possibile utilizzare TADOCommand, un 
componente semplice che non e un dataset. Per dettagli su TADOCommand, 
consultare "Utilizzo di oggetti Command" a pagina 25-17. 



Operazioni con componenti ADO 25-9 



Uso di dataset ADO 



Connessione di un dataset ADO a un datastore 

I dataset ADO possono essere connessi a un datastore ADO in modo collettivo o 
singolarmente. 

Se si vogliono connettere i datasets in modo collettivo, impostare la proprieta 
Connection di ciascun componente dataset a un componente TADOConnection. Ogni 
dataset utilizza quindi la connessione del componente connection ADO. 

ADODataSetl->Connection = ADOConnectionl; 
ADODataSet2->Connection = ADOConnectionl; 

La connessione collettiva di componenti datasets presenta, tra gli altri, i seguenti 
vantaggi: 

• I componenti datasets condividono gli attributi dell'oggetto connessione. 

• Deve essere impostata solo una connessione: quella di TADOConnection. 

• I dataset possono partecipare alle transazioni. 

Per ulteriori informazioni sull'impiego di TADOConnection, consultare "Connessione 
a datastore ADO" a pagina 25-2. 

Se si vogliono connettere singolarmente i datasets, impostare la proprieta 
ConnectionString di ciascun dataset.Ogni dataset che utilizza ConnectionString 
stabilisce la propria connessione al datastore, in modo totalmente indipendente da 
qualsiasi altra connessione al dataset nell'applicazione. 

La proprieta ConnectionString dei dataset ADO funziona come la proprieta 
ConnectionString di TADOConnection: e un set di parametri di connessione delimitati 
da punti e virgola come i seguenti: 

ADODataSetl->ConnectionString = "Provider=YourProvider; Password=SecretWord; " ; 
ADODataSetl->ConnectionString += "User ID=JaneDoe; SERVER=PURGATORY" ; 
ADODataSetl->ConnectionString += "UID=JaneDoe;PWD=SecretWord; 11 
ADODataSetl->ConnectionString += "Initial Catalog=Employee" ; 

In progettazione, e possibile utilizzare il Connection String Editor che aiuta a costruire 
la stringa di connessione. Per informazioni sulle stringhe di connessione, consultare 
"Connessione a un datastore mediante TADOConnection" a pagina 25-3. 

Operazioni con set di record 

La proprieta RecordsetState consente di accedere in modo diretto all'oggetto recordset 
ADO sottostante al componente dataset. Utilizzando questo oggetto, e possibile da 
un'applicazione accedere alle proprieta e chiamare i metodi dell'oggetto recordset. 
L'uso di Recordset per accedere direttamente all'oggetto recordset ADO sottostante 
richiede una buona conoscenza operativa degli oggetti ADO in generale e 
dell'oggetto recordset ADO in particolare. Non si consiglia l'utilizzo diretto 
dell'oggetto recordset a meno che non si abbia familiarita con le operazioni sugli 
oggetti recordset. Per informazioni specifiche sull'utilizzo di oggetti recordset ADO, 
consultare la Guida di Microsoft Data Access SDK. 

La proprieta RecordsetState indica lo stato attuale dell'oggetto recordset sottostante. 
RecordSetState corrisponde alia proprieta State dell'oggetto recordset ADO. II valore 
di RecordsetState e stOpen, stExecuting, oppure stFetching. (TObjectState, il tipo della 
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proprieta RecordsetState, definisce altri valori, ma solo stOpen, stExecuting, e stFetching 
riguardano i recordset). Un valore pari a stOpen indica che il recordset e attivo. Un 
valore pari a stExecuting indica che sta eseguendo un comando. Un valore pari a 
stFetching indica che sta recuperando righe dalla tabella o dalle tabelle associate). 

Utilizzare i valori di RecordsetState per compiere azioni dipendenti dallo stato attuale 
del dataset. Per esempio, una routine di aggiornamento dei dati potrebbe controllare 
la proprieta RecordsetState per verificare se il dataset e attivo e non sta eseguendo 
altre attivita come una connessione o il reperimento di dati. 

Filtraggio di record mediante segnalibri 

I dataset ADO dispongono della funzionalita , comune ai dataset, di contrassegnare e 
restituire record specifici sfruttando i segnalibri. Inoltre, come altri dataset, 
impiegano i filtri per limitare i record disponibili nel dataset. I dataset ADO 
dispongono di un'ulteriore funzione che combina le due funzionalita comuni dei 
dataset: la capacita di filtrare un insieme di record identificati da segnalibri. 

Per filtrare in base a una serie di segnalibri: 

1 Mediante il metodo Bookmark, contrassegnare i record da includere nel dataset 
filtrato. 

2 Mediante il metodo FilterOnBookmarks, filtrare il dataset in modo che vengano 
visualizzati solo i record contrassegnati. 

La procedura e illustrata qui di seguito: 

void __fastcall TForml: :ButtonlClick(TOb]ect *Sender) 
{ 

TBookmarkStr BMl; 

TBookmarkStr BM2; 

BM1 = ADODataSetl->Bookmark; 

BMList->Add (BMl ) ; 

AD0DataSetl->MoveBy(3) ; 

BM2 = ADODataSetl->Bookmark; 

BMList->Add(BM2) ; 

ADODataSetl->FilterOnBookmarks (ARRAYOFCONST ( (BMl , BM2 ) ) ) ; 

} 

Tenere presente che, nell'esempio precedente, i segnalibri vengono inseriti in un 
oggetto lista chiamato BMList. Questo perche l'applicazione possa liberare in seguito 
i segnalibri quando non servono piu. 

Per dettagli sull'impiego dei segnalibri, consultare "Contrassegno e ritorno ai record" 
a pagina 22-9. Per dettagli su altri tipi di filtri, consultare "Visualizzazione e modifica 
di un sottoinsieme di dati usando i filtri" a pagina 22-13. 

Prelievo di record in modalita asincrona 

A differenza di altri dataset, i dataset ADO possono prelevare i dati in modo 
asincrono. Questo permette all'applicazione di fare altro, mentre il dataset si riempie 
di dati presi dal datastore. 

Per controllare se il dataset preleva i dati in modo asincrono, se pure li preleva, si 
utilizza la proprieta ExecuteOptions. ExecuteOptions regola il modo in cui il dataset 
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preleva i record quando si chiama Open o si imposta la proprieta Active a true. Se il 
dataset rappresenta una query o una procedura registrata che non restituisce record, 
ExecuteOptions regola il modo in cui vengono eseguite la query o la procedura 
registrata quando si chiamano ExecSQL o ExecProc. 

ExecuteOptions e un insieme che include zero o piu dei seguenti valori: 
Tabella 25.3 Opzioni di esecuzione dei dataset ADO 



Opzione di esecuzione 

eoAsyncExecute 
eoAsyncFetch 

eoAsyncFetchNonBlocking 
eoExecuteNoRecords 



Significato 

II comando o 1'operazione di prelievo dati vengono eseguiti in 
modo asincrono. 

II dataset prima preleva in modo sincrono il numero di record 
specificati dalla proprieta CacheSize, quindi preleva le eventuali 
righe rimanenti in modo asincrono. 

I prelievi asincroni di dati o l'esecuzione di comandi non 
interrompono il thread di esecuzione attivo. 

Un comando o una procedura registrata che non restituiscono dati. 
Le eventuali righe recuperate, vengono eliminate e non restituite. 



Uso di aggiornamenti batch 

Un approccio per la gestione degli aggiornamenti in cache consiste nel connettere il 
dataset ADO a un dataset client utilizzando un provider di dataset. Questo approccio 
e discusso in "Utilizzo di un dataset client per registrare in cache gli aggiornamenti" 
a pagina 27-17. 

Tuttavia, i componenti dataset ADO sono in grado di supportare gli aggiornamenti 
memorizzati nella cache, che chiamano aggiornamenti batch. La seguente tabella 
elenca le corrispondenze tra la memorizzazione di aggiornamenti nella cache 
utilizzando un dataset client, oppure utilizzando le f unzionalita di aggiornamento 
batch: 



Tabella 25.4 Confronto tra gli aggiornamenti in cache di ADO e gli aggiornamenti in cache nel dataset client 



Dataset ADO TCIientDataSet 

LockType Non utilizzato: i dataset 

client memorizzano sempre 
gli aggiornamenti nella cache 

CursorType Non utilizzato: i dataset 

client funzionano sempre con 
un"'istantanea" in memoria 
dei dati 

RecordStatus UpdateStatus 



FilterGroup StatusFilter 



Descrizione 

Specifica se il dataset e aperto in modo 
aggiornamento batch. 

Specifica in che misura il dataset ADO e isolato 
dalle modifiche sul server. 



Indica l'eventuale tipo di aggiornamento che si e 
verificato sulla riga corrente. RecordStatus fornisce 
piu informazioni di UpdateStatus. 

Specifica quali tipi di record sono disponibili. 
FilterGroup fornisce una gamma piu ampia di 
informazioni. 
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Tabella 25.4 Confronto tra gli aggiornamenti in cache di ADO e gli aggiornamenti in cache nel dataset client 
Dataset ADO TCIientDataSet Descrizione 

UpdateBatch ApplyUpdates Applica al server di database gli aggiornamenti 

nella cache.A differenza di ApplyUpdates, 
UpdateBatch permette di limitare i tipi di 
aggiornamenti da applicare. 

CancelBatch CancelUpdates Elimina gli aggiornamenti in sospeso e torna ai 

valori originari. A differenza di CancelUpdates, 
CancelBatch permette di limitare i tipi di 
aggiornamenti da annullare. 



L'utilizzo delle funzionalita degli aggiornamenti batch dei componenti dataset ADO 
puo essere schematizzata come segue: 

• Apertura del dataset in modalita aggiornamento batch 

• Ispezione dello stato di aggiornamento delle singole righe 

• Filtraggio di piu righe in base alio stato di aggiornamento 

• Applicazione degli aggiornamenti batch alle tabelle di base 

• Annullamento degli aggiornamenti batch 

Apertura del dataset in modalita aggiornamento batch 

Per aprire un dataset ADO in modalita aggiornamento batch, devono essere 
soddisfatte le seguenti condizioni: 

1 La proprieta CursorType del componente deve essere impostata a ctKeySet (il 
valore predefinito della proprieta) oppure a ctStatic. 

2 La proprieta LockType deve essere impostata a ItBatchOptimistic. 

3 II comando deve essere una query SELECT. 

Prima di attivare il componente dataset, impostare le proprieta CursorType e LockType 
ai valori indicati in precedenza. Assegnare un'istruzione SELECT alia proprieta 
CommandText del componente (per un TADODataSet) oppure alia proprieta SQL (nel 
caso di un TADOQuery). Per i componenti TADOStoredProc, impostare 
ProcedureName al nome di una procedura registrata che restituisce un set risultato. 
Queste proprieta possono essere impostate in fase di progetto mediante l'Object 
Inspector oppure in fase di esecuzione dal programma. L'esempio seguente mostra la 
preparazione di un componente TADODataSet per la modalita aggiornamento batch. 

ADODataSetl->CursorLocation = clUseClient ; 
ADODataSetl->CursorType = ctStatic; 
ADODataSetl->LockType = ItBatchOptimistic; 
ADODataSetl->CommandType = cmdText; 
ADODataSetl->CommandText = "SELECT * FROM Employee"; 

Dopo aver aperto un dataset in modalita aggiornamento batch, tutte le modifiche ai 
dati vengono inserite in cache invece di essere applicate direttamente alle tabelle di 
base. 
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Ispezione dello stato di aggiornamento delle singole righe 

Lo stato di aggiornamento di una certa riga si determina rendendola attiva e quindi 
ispezionando la proprieta RecordStatus del componente dati ADO. RecordStatus 
rispecchia lo stato di aggiornamento della riga corrente e solamente di quella riga. 

switch (ADOQuery->RecordStatus) 

{ 

case rsUnmodified: 

StatusBarl->Panels->Items [0] ->Text = "Unchanged record" ; 

break ; 
case rsModified: 

StatusBarl->Panels->Items [0] ->Text = "Changed record" ; 

break ; 
case rsDeleted: 

StatusBarl->Panels->ltems [0] ->Text = "Deleted record"; 

break ; 
case rsNew: 

StatusBarl->Panels->Items [0] ->Text = "New record" ; 
break ; 

} 

Filtraggio di piu righe in base alio stato di aggiornamento 

E possibile filtrare un recordset per visualizzare solo quelle righe che appartengono a 
un gruppo di righe con lo stesso stato di aggiornamento utilizzando la proprieta 
FilterGroup. Impostare FilterGroup alia costante TFilterGroup che rappresenta lo stato 
di aggiornamento delle righe che si vogliono visualizzare. Un valore pari afgNone (il 
valore predefinito per questa proprieta) specifica che non e stato applicato alcun 
filtrazione e tutte le righe (tranne quelle marcate per cancellazione) sono visibili, 
indipendentemente dal loro stato di aggiornamento. L'esempio seguente provoca la 
visualizzazione delle sole righe per cui e pendente un aggiornamento batch. 

FilterGroup = fgPendingRecords; 
Filtered = true; 

Affinche la proprieta FilterGroup abbia effetto, la proprieta Filtered del componente 
dataset ADO deve essere impostata a true. 

Applicazione degli aggiornamenti batch alle tabelle di base 

Applicare le modifiche in sospeso ai dati, che non sono state ancora applicate o che 
sono state annullate, chiamando il metodo UpdateBatch. I cambiamenti apportati alle 
righe che sono state modificate e applicate vengono trasferiti nelle tabelle di base su 
cui e basato il recordset. Una riga inserita in cache e contrassegnata per la 
cancellazione provoca la cancellazione della riga corrispondente dalla tabella di base. 
Un inserimento di record (presente nella cache ma non nella tabella di base) viene 
aggiunto alia tabella di base. Le righe modificate fanno si che le colonne nelle righe 
corrispondenti nelle tabelle di base vengano modificate in base ai nuovi valori di 
colonna presenti nella cache. 

UpdateBatch accetta un parametro, un valore TAffectRecords. Facoltativamente, e 
possibile passare come parametro ad UpdateBatch un valore di TAffectRecords. 
L'esempio seguente provoca l'applicazione delle modifiche apportate alia sola riga 
corrente: 
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ADODataSetl->UpdateBatch(arCurrent) ; 

Annullamento degli aggiornamenti batch 

Annullare le modif iche ai dati in sospeso, che non sono state ancora annullate o 
applicate, chiamando il metodo CancelBatch. Quando si annullano degli 
aggiornamenti batch in sospeso, i valori di campo nelle righe sottoposte a modifica 
che sono state modificate tornano ai valori in vigore prima dell'ultima chiamata a 
CancelBatch o UpdateBatch, se l'uno o l'altro e stato chiamato, o prima del lotto 
corrente di modifiche in sospeso. 

CancelBatch accetta un parametro, un valore TAffectRecords. II passaggio di un 
qualsiasi altro valore, ad eccezione di arAll, provoca l'annullamento solo di un 
sottoinsieme delle modifiche pendenti. L'esempio seguente annulla tutte le 
modifiche pendenti: 

ADODataSetl->CancelBatch( arAll) ; 

Caricamento e salvataggio di dati su file 

I dati reperiti mediante un componente dataset ADO possono essere salvati in un file, 
sullo stesso computer o su uno differente, in modo da poter eseguire ricerche in una 
fase successiva. I dati vengono salvati in uno dei due formati proprietari: ADTG e 
XML. Questi due formati di file sono gli unici formati supportati da ADO. 
Comunque, non e detto che entrambi i formati siano supportati in tutte le versioni 
ADO. Consultare la documentazione ADO relativa alia versione utilizzata per 
determinare quali sono i formati file di salvataggio supportati. 

II salvataggio di dati in un file avviene utilizzando il metodo SaveToFile. SaveToFile 
accetta due parametri, il nome del file su cui i dati sono salvati e il formato (ADTG o 
XML) in cui salvarli. Si indica il formato del file da salvare impostando il parametro 
Format a pfADTG o a pfXML. Se il file specificato dal parametro FileName esiste gia , 
SaveToFile solleva una EOleException. 

II reperimento di dati da un file avviene utilizzando il metodo LoadFromFile. 
LoadFromFile accetta un solo parametro, il nome del file da caricare. Se il file 
specificato non esiste, LoadFromFile solleva un' eccezione EOleException. II 
componente dataset viene attivato automaticamente appena si esegue la chiamata al 
metodo LoadFromFile. 

Nell'esempio seguente, la prima procedura salva il dataset, reperito dal componente 
ADODataSetl di tipo TADODataSet, in un file. II file di destinazione e un file di tipo 
ADTG di nome SaveFile, salvato su un'unita locale. La seconda procedura carica 
questo file salvato nel componente ADODataSetl di tipo TADODataSet. 

void __fastcall TForml: :SaveBtnClick(TObject *Sender) 

{ 

if (FileExists("c:\\SaveFile") ) 

{ 

DeleteFile("c:\\SaveFile") ; 

Statusbarl->Panels->ltems [0] ->Text = "Save file deleted!"; 

} 

ADODataSetl->SaveToFile ( "c : WSaveFile" ) ; 

} 
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void __fastcall TForml: :LoadBtnClick(TObject *Sender) 
{ 

if (FileExists("c:\\SaveFile") ) 

ADODataSetl->LoadFromFile ( "c : WSaveFile" ) ; 
else 

Statusbarl->Panels->Items [0] ->Text = "Save file does not exist!"; 

} 

I dataset che effettuano il salvataggio e il caricamento dei dati non devono 
necessariamente essere nel formato visto in precedenza, nella stessa applicazione o 
sullo stesso computer. Questo consente un trasferimento dei dati di tipo briefcase da 
un computer a un altro. 

Utilizzo di TADODataSet 



TADODataSet e un dataset di uso comune usato per lavorare con i dati di un 
datastore ADO. A differenza degli altri componenti dataset ADO, TADODataSet non 
e di tipo tabella, di tipo query o di tipo procedura registrata. Tuttavia, funziona 
indifferentemente come uno qualsiasi di questi tre tipi: 

• Come un dataset di tipo tabella, TADODataSet permette di rappresentare tutte le 
righe e le colonne di una singola tabella di database. Per utilizzarlo in questo 
modo, si imposta la proprieta CommandType a cmdTable e la proprieta 
CommandText al nome della tabella. TADODataSet supporta attivita di tipo 
tabellare come 

• Assegnazione di indici per ordinare i record o per costituire la base di ricerche 
basate su record. Oltre che con le proprieta e i metodi di indicizzazione 
standard descritti in "Ordinamento dei record con indici" a pagina 22-27, 
TADODataSet consente, impostando la proprieta Sort, di ordinare utilizzando 
indici temporanei. Le ricerche basate su indice svolte tramite il metodo Seek 
utilizzano l'indice corrente. 

• Svuotamento del dataset. II metodo DeleteRecords consente un controllo piu 
incisivo che non i metodi analoghi di altri dataset di tipo tabella, perche 
permette di specificare quali record cancellare. 

Le attivita di tipo tabella supportate da TADODataSet sono disponibili anche 
quando non si sta utilizzando un CommandType di cmdTable. 

• Come i dataset di tipo query, TADODataSet permette di specificare un singolo 
comando SQL da eseguire quando il dataset viene aperto. Per utilizzarlo in questo 
modo, impostare la proprieta CommandType a cmdText e la proprieta CommandText 
al comando SQL da eseguire. In progettazione, e possibile fare doppio clic sulla 
proprieta CommandText nell'Object Inspector per farsi aiutare dal Command Text 
editor a impostare il il comando SQL. TADODataSet supporta attivita query-type 
come 

• Utilizzo dei parametri nel testo di query. Per i dettagli sulle query 
parametrizzate consultare "Utilizzo dei parametri nelle query" a pagina 22-46. 
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• Configurare le relazioni master /detail utilizzando parametri. Per i dettagli di 
impiego, consultare "Impostazione di relazioni master /detail mediante 
parametri" a pagina 22-49. 

• Preparazione in anticipo della query per migliorare le prestazioni impostando a 
true la proprieta Prepared. 

• Come un dataset di tipo procedura registrata, TADODataSet permette di 

specificare una procedura registrata che e eseguita quando si apre il dataset. Per 
utilizzarlo in questo modo, si impostano a cmdStoredProc la proprieta 
CommandType, e al nome della procedura registrata la proprieta CommandText. 
TADODataSet supporta le attivita di tipo procedura memorizzate come 

• Operazioni con i parametri di una procedura registrata. Per i dettagli sui 
parametri di una procedura registrata consultare "Operazioni con i parametri 
delle procedure registrate" a pagina 22-53. 

• Prelievo di piu set risultato. Consultare "Prelievo di piu set risultato" a 
pagina 22-57. 

• Preparazione in anticipo della procedura registrata per migliorare le prestazioni 
impostando la proprieta Prepared a true. 

Inoltre, TADODataSet permette di gestire dati memorizzati nei file impostando la 
proprieta CommandType a cmdFile e la proprieta CommandText al nome al file. 

Prima di impostare le proprieta CommandText e CommandType, bisogna connettere 
TADODataSet con un datastore impostando la proprieta Connection o 
ConnectionString. La procedura e spiegata in "Connessione di un dataset ADO a un 
datastore" a pagina 25-10. In alternativa, si puo utilizzare un oggetto DataSpace RDS 
per connettere TADODataSet a un server applicativo basato su ADO. Per utilizzare 
un oggetto DataSpace RDS, impostare la proprieta RDSConnection a un oggetto 
TRDSConnection. 

Utilizzo di oggetti Command 



Nell'ambiente ADO, i comandi sono rappresentazioni testuali di richieste di azioni 
specifiche per il provider. Tipicamente, sono istruzioni SQL di tipo DDL (Data 
Definition Language) o DML (Data Manipulation Language). II linguaggio utilizzato 
nei comandi e specifico per ogni provider, ma di solito conforme con lo standard 
SQL-92 del linguaggio SQL. 

Benche si possano sempre eseguire i comandi mediante TADOQuery, non conviene 
sobbarcarsi il carico di elaborazione causato dall'impiego di un componente dataset, 
specialmente se il comando non restituisce un set risultato. Come alternativa e 
possibile utilizare il componente TADOCommand che e un oggetto leggero progettato 
per eseguire comandi, uno alia volta. TADOCommand e destinato principalmente 
all'esecuzione di quei comandi che non restituiscono un set risultato, come le 
istruzioni SQL di tipo DDL (Data Definition Language). Tuttavia, grazie a una 
ridefinizione del metodo Execute, e in grado di restituire un set risultato che puo 
essere assegnato alia proprieta RecordSet di un componente ADO dataset. 
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Di solito, lavorare con TADOCommand e molto simile a lavorare con TADODataSet, 
salvo per il fatto che non si possono utilizzare i metodi di dataset standard per 
prelevare dati, spostarsi tra i record, modificare i dati e cosi via. Gli oggetti 
TADOCommand si connettono a un datastore proprio come i dataset ADO. Per i 
dettagli, consultare "Connessione di un dataset ADO a un datastore" a pagina 25-10 
for details. 

Le sezioni seguenti spiegano come specificare ed eseguire i comandi utilizzando 
TADOCommand. 

Specifica del comando 



I comandi di un componente TADOCommand si specificano mediante la proprieta 
CommandText. Come TADODataSet, TADOCommand permette di specificare il 
comando in vari modi, a seconda della proprieta CommandType. I possibili valori di 
CommandType includono: cmdText (usato se il comando e un'istruzione SQL), 
cmdTable (se e un nome di tabella) e cmdStoredProc (se il comando e il nome di una 
procedura registrata). In fase di progettazione, selezionare dall'elenco nell'Object 
Inspector il tipo di comando appropriato. In esecuzione, assegnare alia proprieta 
CommandType un valore di tipo TCommandType. 

ADOCommandl->CommandText = "AddEmployee" ; 
ADOCommandl->CommandType = cmdStoredProc; 

Se non viene specificato alcun tipo particolare, si lascia al server l'incombenza di 
decidere al meglio in base al comando contenuto in CommandText. 

CommandText pud contenere il testo di una query SQL che include parametri, o il 
nome di una procedura registrata che utilizza parametri. E necessario fornire i valori 
dei parametri, che vengono collegati ai parametri prima di eseguire il comando. Per i 
dettagli, consultare "Gestione dei parametri di comando" a pagina 25-20. 

Utilizzo del metodo Execute 



Prima che il componente TADOCommand possa eseguire il suo comando, deve aver 
stabilito una connessione valida con un datastore. II collegamento viene stabilito 
esattamente come avviene con i dataset ADO. Per i dettagli, consultare "Connessione 
di un dataset ADO a un datastore" a pagina 25-10. 

Per eseguire il comando, chiamare il metodo Execute. Execute e un metodo caricato in 
sovrapposizione che permette di scegliere il modo piu appropriato per eseguire il 
comando. 

Per i comandi che non richiedono parametri e dei quali non interessa il numero di 
record interessati, si chiama Execute senza nessun parametro: 

ADOCommandl->CommandText = "Updatelnventory" ; 
ADOCommandl->CommandType = cmdStoredProc; 
ADOCommandl->Execute ( ) ; 
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Altre versioni di Execute permettono di fornire i valori dei parametri utilizzando un 
array Variant, e ottenendo cosi il numero di record interessati dal comando. 

Per informazioni sull'esecuzione di comandi che restituiscono un set risultato, 
consultare "Reperimento di set risultato con comandi" a pagina 25-19. 



Annullamento di comandi 



Se si esegue il comando in modo asincrono, allora dopo avere chiamato Execute e 
possibile interrompere l'esecuzione chiamando il metodo Cancel: 

void __fastcall TDataForm: :ExecuteButtonClick(TObject *Sender) 
{ 

ADOCommandl->Execute ( ) ; 

} 

void __fastcall TDataForm: :CancelButtonClick(TObject *Sender) 
{ 

ADOCommandl->Cancel ( ) ; 

} 

II metodo Cancel sortisce un effetto solo se c'e un comando in sospeso e il comando 
era stato eseguito in modo asincrono (il parametro ExecuteOptions del metodo Execute 
contiene eoAsynchExecute). Un comando viene definito "in sospeso" se e stato 
chiamato il metodo Execute ma il comando non e stato ancora completato oppure e 
andato in time-out. 

Se un comando non viene annullato o completato entro il numero di secondi 
specificato nella proprieta CommandTimeout, il comando va in time-out. Per 
impostazione predefinita, i comandi vanno in time-out dopo 30 secondi. 



Reperimento di set risultato con comandi 

A differenza dei componenti TADOQuery, che utilizzano vari metodi di esecuzione, a 
seconda che restituiscano un set risultato o meno, TADOCommand utilizza sempre il 
comando Execute per eseguire il comando, che restituisca o no un set risultato. 
Quando restituisce un set risultato, Execute restituisce un'interfaccia verso 
l'interfaccia ADO _RecordSet. 

II modo piu conveniente per lavorare con questa interfaccia e di assegnarla alia 
proprieta RecordSet di un dataset ADO. 

Ad esempio, il seguente codice utilizza TADOCommand (ADOCommandl) per 
eseguire una query SELECT, che restituisce un set risultato. Questo set risultato viene 
poi assegnato alia proprieta RecordSet di un componente TADODataSet 
(ADODataSetl). 

ADOCommandl->CommandText = "SELECT Company, State "; 
ADOCommandl->CommandText += "FROM customer "; 
ADOCommandl->CommandText += "WHERE State = :StateParam" ; 
ADOCommandl->CommandType = cmdText; 

ADOCommandl->Parameters->ParamByName ( "StateParam" ) ->Value = "HI" ; 
ADOCommandl->Recordset = ADOCommandl - >Execute () ; 



Operazioni con componenti ADO 25-19 



Utilizzo di oggetti Command 

Non appena il set risultato viene assegnato alia proprieta Recordset del componente 
dataset ADO, il componente dataset viene automaticamente attivato e i dati 
diventano disponibili. 

Gestione dei parametri di comando 



Sono due i modi in cui un oggetto TADOCommand puo utilizzare i parametri: 

• La proprieta CommandText puo specificare una query che include dei parametri. 
Lavorare con le query parametrizzate in TADOCommand e come usare una query 
parametrizzata in un dataset ADO. Per i dettagli sulle query parametrizzate 
consultare "Utilizzo dei parametri nelle query" a pagina 22-46. 

• La proprieta CommandText puo specificare una procedura registrata che utilizza 
parametri. I parametri di una procedura registrata funzionano piu o meno come 
TADOCommand con i dataset ADO. Per i dettagli sui parametri di una procedura 
registrata consultare "Operazioni con i parametri delle procedure registrate" a 
pagina 22-53. 

Ci sono due modi per fornire valori dei parametri quando si lavora con 
TADOCommand: si possono fornire quando si chiama il metodo Execute, oppure 
specificarli anticipatamente mediante la proprieta Parameters. 

II metodo Execute e caricato in sovrapposizione per includere versioni che accettano 
un set di valori di parametro sotto forma di array Variant. La cosa e utile quando si 
desidera fornire velocemente i valori dei parametri senza l'aggravio di configurare la 
proprieta Parameters: 

Variant Values [2] ; 
Values[0] = Editl->Text; 
Values [1] = Dated ; 

ADOCommandl . Execute ( VarArrayOf (Values , 1 ) ) ; 

Quando si lavora con le procedure registrate che restituiscono parametri di output, 
bisogna invece utilizzare la proprieta Parameters. Anche se non si ha bisogno di 
leggere i parametri di output, conviene usare la proprieta Parameters, che permette di 
fornire i parametri in fase di progetto e di lavorare con le proprieta TADOCommand 
nello stesso modo in cui si lavora con i parametri sui dataset. 

Quando si imposta la proprieta CommandText, la proprieta Parameters viene 
aggiornata automaticamente per riflettere i parametri nella query, o quelli utilizzati 
dalla procedura registrata. In progettazione, accedere ai parametri utilizzando il 
Parameter Editor, attivato facendo clic nell'Object Inspector sui pulsante ellissi della 
proprieta Parameters. In fase di esecuzione, per impostare (o recuperare) i valori di 
ciascun parametro utilizzare le proprieta e i metodi di TParameter. 

ADOCommandl->CommandText = "INSERT INTO Talley "; 
ADOCommandl ->CommandText += "(Counter) "; 
ADOCommandl->CommandText += "VALUES ( :NewValueParam) " ; 
ADOCommandl->CommandType = cmdText; 

ADOCommandl->Parameters->ParamByName ( "NewValueParam" ) ->Value = 57; 
ADOCommandl->Execute ( ) 
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Uso di dataset unidirezionali 



dbExpress e un gruppo di driver di database leggeri che consentono un accesso rapido 
ai server di database SQL. Per ogni database supportato, dbExpress dispone di un 
driver che adatta il software specifico del server a un set di classi uniformi di 
dbExpress. Quando si distribuisce un'applicazione database che utilizza dbExpress, 
con i file dell'applicazione generata e necessario includere solamente una dll (il 
driver specifico per il server. 

dbExpress consente di accedere a database utilizzando dataset unidirezionali. I 
dataset unidirezionali sono progettati per consentire un rapido accesso alle 
informazioni di database, con un minimo appesantimento. Come altri dataset, sono 
in grado di inviare un comando SQL al server di database e, se il comando restituisce 
un set di record, ottengono un cursor per accedere a quei record. Tuttavia, i dataset 
unidirezionali possono recuperare solo un cursor unidirezionale. Essi non 
memorizzano i dati in memoria, il che li rende piu rapidi e bisognosi di meno risorse 
rispetto ad altri tipi di dataset. Tuttavia, poiche i record non vengono bufferizzati, i 
dataset unidirezionali sono anche meno flessibili di altri dataset. Molte funzionalita 
introdotte da TDataSet o non sono implementate nei dataset unidirezionali o causano 
il sollevamento di eccezioni. Per esempio: 

• Gli unici metodi di navigazione supportati sono i metodi First e Next. La maggior 
parte degli altri metodi solleva eccezioni. Alcuni, come i metodi coinvolti nel 
supporto dei segnalibri, semplicemente non fanno niente. 

• Non forniscono alcun supporto interno per l'editing perche tale operazione 
richiede un buffer per conservare le modifiche. La proprieta CanModify e sempre 
false e, pertanto, il tentativo di porre il dataset in modalita editing non va mai a 
buon fine. E possibile, comunque, utilizzare i dataset unidirezionali per 
aggiornare i dati utilizzando un comando SQL UPDATE o fornire il tradizionale 
supporto per l'editing utilizzando un dataset client dbExpress o connettendo il 
dataset a un dataset client (consultare "Collegamento a un altro dataset" a 
pagina 18-10). 

• Non forniscono alcun supporto per i filtri in quanta i filtri operano con piu record, 
il che richiede l'utilizzo di un buffer. Se si prova a filtrare un dataset 
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unidirezionale, viene sollevata un'eccezione. Tutti i limiti, in base a cui vengono 
visualizzati i dati, devono essere invece imposti utilizzando il comando SQL che 
definisce i dati del dataset. 

• Non forniscono alcun supporto per i campi di consultazione, cosa che richiede 
anch'essa un buffer per conservare piu record contenenti i valori da consultare. Se 
si definisce un campo di consultazione su un dataset unidirezionale, non potra 
operare correttamente. 

Malgrado queste limitazioni, i dataset unidirezionali rappresentano un modo potente 
per accedere ai dati. Risultano essere un meccanimo di accesso ai dati rapidissimo e 
molto semplice da utilizzare e distribuire. 

Tipi di dataset unidirezionali 



La pagina dbExpress della Component palette contiene quattro tipi di dataset 
unidirezionali: TSQLDataSet, TSQLQuery, TSQLTable e TSQLStoredProc. 

TSQLDataSet e il piu generico dei quattro. E possibile utilizzare un dataset SQL per 
rappresentare tutti i dati disponibili tramite dbExpress o per inviare comandi a un 
database a cui si accede mediante dbExpress. Questo e il componente che si consiglia 
di utilizzare per operare con tabelle di database nelle nuove applicazioni database. 

TSQLQuery e un dataset di tipo query che incapsula un'istruzione SQL e permette 
alle applicazioni di accedere ai record risultanti, nel caso ve ne siano. Per 
informazioni sull'utilizzo di dataset di tipo query, vedere "Utilizzo di dataset di tipo 
query" a pagina 22-43. 

TSQLTable e un dataset di tipo tabella che rappresenta tutte le righe e colonne di una 
singola tabella di database. Per informazioni sull'utilizzo di dataset di tipo tabella, 
vedere "Utilizzo dei dataset di tipo tabella" a pagina 22-26. 

TSQLStoredProc e un dataset di tipo procedura registrata che esegue una procedura 
registrata definita su un server di database. Per informazioni sull'utilizzo di dataset 
di tipo procedura registrata, vedere "Utilizzo di dataset di tipo procedura registrata" 
a pagina 22-52. 

La pagina dbExpress include anche TSQLClientDataSet, che non e un dataset 
unidirezionale. Piuttosto, e un dataset client che utilizza un dataset unidirezionale 
internamente per accedere ai suoi dati. 

Connessione ai server di database 



Quando si opera con un dataset unidirezionale la prima operazione consiste nel 
connetterlo a un server di database. In progettazione, una volta che un dataset ha una 
connessione attiva a un server di database, l'Object Inspector e in grado di presentare 
delle liste a discesa con i valori di altre proprieta. Ad esempio, quando si rappresenta 
una procedura registrata, e necessario avere una connessione attiva prima che 
l'Object Inspector sia in grado di elencare quali procedure registrate sono disponibili 
sul server. 
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La connessione a un server di database e rappresentata da un componente separato 
TSQLConnection. Si opera con TSQLConnection come con qualsiasi altro componente 
di connessione ai database. Per informazioni sull'utilizzo di componenti database 
connection, vedere il Capitolo 21, "Connessione ai database". 

Per utilizzare TSQLConnection per connettersi un dataset unidirezionale a un server 
di database, impostare la proprieta SQLConnection. In progettazione, e possibile 
scegliere il componente SQL connection da una lista a discesa nell'Object Inspector. 
Se si fa questa assegnazione in esecuzione, e bene accertarsi che la connessione sia 
attiva: 

SQLDataSetl->SQLConnection = SQLConnectionl; 
SQLConnectionl->Connected = true; 

Di solito, tutti i dataset unidirezionali in un'applicazione condividono lo stesso 
componente connection, a meno che non si stia operando con dati provenienti da piu 
server di database. Tuttavia, potrebbe essere necessario utilizzare un componente 
connection diverso per ogni dataset nel caso il server non supporti piu istruzioni per 
ogni connessione. Controllare se il server il database richiede una diversa 
connessione per ogni dataset leggendo la proprieta MaxStmtsPerConn. Per 
impostazione predefinita, TSQLConnection genera connessioni appena occorre nel 
caso il server limiti il numero di istruzioni che possono essere eseguite per ogni 
singola connessione. Se si desidera tenere una traccia rigorosa delle connessioni 
utilizzate, impostare la proprieta AutoClone a false. 

Prima di assegnare la proprieta SQLConnection, e necessario impostare il componente 
TSQLConnection in modo che identifichi il server di database e tuut i parametri di 
connessione necessari (inclusi il database da utilizzare sul server, il nome host della 
macchina su cui il server e in esecuzione, il nome utente, la password, e cosi via). 

Impostazione di TSQLConnection 



Per descrivere una connessione al database in modo sufficientemente dettagliato 
affinche TSQLConnection sia in grado di aprire una connessione, e necessario 
identificare sia il driver da utilizzare sia un insieme di parametri di connessione che 
vengono passati a quel driver. 

Identificazione del driver 

II driver e identificato dalla proprieta DriverName che e il nome di un driver installato 
di dbExpress, come INTERBASE, ORACLE, MYSQL o DB2. II nome del driver e 
associato a due file 

• II driver dbExpress. Questi e una libreria a collegamento dinamico con un nome 
simile a dbexpint.dll, dbexpora.dll, dbexpmys.dll o dbexpdb2.dll. 

• La libreria a collegamento dinamico fornita dal produttore di database per il 
supporto sul lato client. 

La relazione tra questi due file oggetto condivisi e il nome del database viene 
memorizzata in un file di nome dbxdrivers.ini che viene aggiornato quando si 
installa un driver dbExpress. Di solito, non e necessario occuparsi di questi file perche 
il componente connection SQL li ricerchera in dbxdrivers.ini non appena si impostera 
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il valore della proprieta DriverName. Quando si imposta la proprieta DriverName, 
TSQLConnection imposta automaticamente le proprieta LibraryName e VendorLib ai 
nomi delle dlld associate. Una volta che Libraryname e VendorLib sono state 
impostateJ'applicazione non ha piu bisogno di appoggiarsi a dbxdrivers.ini. (Cio 
significa che non e necessario distribuire il file dbxdrivers.ini con l'applicazione, a 
meno che non si imposti la proprieta DriverName al momento dell'esecuzione.) 

Specifica dei parametri di connessione 

La proprieta Params e una lista di stringhe che elenca coppie di tipo nome/valore. 
Ogni coppia assume il formato Name = Value, dove Name e il nome del parametro e 
Value e il valore che gli si vuole assegnare. 

I particolari parametri necessari dipendono dal server di database che si utilizza. 
Tuttavia, per tutti i server e richiesto un particolare parametro, Database. II suo valore 
dipende dal server che si utilizza. Ad esempio, con InterBase, Database e il nome del 
file .gdb, con ORACLE e l'elemento in TNSNames.ora, mentre con DB2 e il nome del 
nodo sul lato client. 

Altri parametri tipici includono lo User_Name (il nome da utilizzare per il login), 
Password (la password per User_Name), HostName (il nome della macchina o 
l'indirizzo IP dove e situato il server), e Translsolation (il livello al cui raggiungimento 
le transazioni introdotte sono consapevoli delle modifiche apportate da altre 
transazioni). Quando si specifica un nome di driver, la proprieta Params viene 
precaricata con tutti i parametri necessari per quel tipo di driver, inizializzati ai valori 
predefiniti. 

Poiche Params e una lista di stringhe, in progettazione e possibile fare doppio clic 
sulla proprieta Params nell'Object Inspector per modificare i parametri utilizzando lo 
String List editor. In esecuzione, utilizzare la proprieta Paramsv.Values per assegnare i 
valori ai singoli parametri. 

Assegnazione di un nome a una descrizione della connessione 

Benche sia sempre possibile specificare una connessione utilizzando solo le proprieta 
DatabaseName e Params, puo essere piu conveniente assegnare un nome a una 
specifica combinazione e quindi identificare la connessione soltanto mediante il 
nome. E possibile assegnare un nome alle combinazioni di database di dbExpresse 
parametri, e di salvarle quindi in un file di nome dbxconnections.ini. II nome di ogni 
combinazione viene detto nome della connessione. 

Una volta che si e definito il nome della connessione, e possibile identificare una 
connessione di database semplicemente impostando la proprieta ConnectionName a 
un nome di connessione valido. L'impostazione di ConnectionName imposta 
automaticamente le proprieta DriverName e Params. Una volta impostato 
ConnectionName, e possibile modificare la proprieta Params per differenziarla 
temporaneamente rispetto al set salvato di valori di parametro; la modifica della 
proprieta DriverName azzera invece sia Params sia ConnectionName. 

Uno dei vantaggi derivanti dall'utilizzo di nomi di connessione si presenta quando si 
sviluppa una applicazione utilizzando un certo database (ad esempio Local 
InterBase), ma la si distribuisce per utilizzarla con un altro (ad esempio ORACLE). In 
questo caso, DriverName e Params probabilmente saranno diversi sul sistema su cui si 
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distribuira l'applicazione rispetto ai valori utilizzati durante lo sviluppo. E possibile 
scambiare le due descrizioni di connessione semplicemente utilizzando due versioni 
del file dbxconnections.ini. In progettazione, l'applicazione carica DriverName e 
Params dalla versione di progettazione di del file dbxconnections.ini. Quindi, quando 
si distribuira l'applicazione, l'applicazione carichera questi valori da una versione 
differente di dbxconnections.ini che utilizza il database "reale". Tuttavia, perche 
questo funzioni, e necessario fare in modo che il componente connection carichi di 
nuovo le proprieta DriverName e Params. E possibile farlo in due modi: 

• Impostare la proprieta LoadParamsOnConnect a true. In questo modo si forza 
TSQLConnection a impostare automaticamente DriverName e Params ai valori 
associati a ConnectionNamenel file dbxconnections.ini non appena viene aperta la 
connessione. 

• Chiamare il metodo LoadParamsFromlniFile. Questo metodo imposta DriverName e 
Params ai valori associati a ConnectionName nel file dbxconnections.ini( oppure in 
un altro file specif icato). Si puo scegliere di utilizzare questo metodo se si 
desiderano ridefinire alcuni valori di parametro prima di aprire la connessione. 

Utilizzo di Connection Editor 

Le relazioni tra i nomi di connessione e i rispettivi driver e parametri di connessione 
associati sono memorizzate nel file dbxconnections.ini. E possibile creare o 
modificare queste associazioni utilizzando Connection Editor. 

Per visualizzare Connection Editor, fare doppio clic sul componente TSQLConnection. 
Verra visualizzato Connection Editor che presenta una lista a discesa contenente tutti 
i driver disponibili, una lista di nomi di connessione per il driver attualmente 
selezionato e una tabella che elenca i parametri di connessione per il nome di 
connessione attualmente selezionato. 

E possibile utilizzare questa finestra di dialogo per indicare la connessione da 
utilizzare selezionando un nome di driver e di connessione. Una volta scelta la 
configurazione desiderata, fare clic sul pulsante Test Connection per controllare che 
si sia scelta una configurazione valida. 

Inoltre, e possibile utilizzare questa finestra di dialogo per modificare le connessioni 
con nome presenti in dbxconnections.ini: 

• Modificare i valori dei parametri nella tabella dei parametri per modificare la 
connessione con nome attualmente selezionata. Appena si esce dalla finestra di 
dialogo facendo clic su OK, i nuovi valori dei parametri vengono salvati nel file 
dbxconnections.ini. 

• Fare clic sul pulsante Add Connection per definire una connessione con nome. 
Verra visualizzata una finestra di dialogo in cui si specif icano il driver da 
utilizzare e il nome della nuova connessione. Una volta assegnato un nome alia 
connessione, modificare i parametri per specificare la connessione desiderata e 
fare clic sul pulsante OK per salvare la nuova connessione in dbxconnections.ini. 

• Fare clic sul pulsante Delete Connection per cancellare da dbxconnections.ini la 
connessione con nome attualmente selezionata. 
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• Fare clic sul pulsante Rename Connection per modificare il nome della 
connessione con nome attualmente selezionata. Si noti che tutte le modifiche 
apportate ai parametri vengono salvate con il nuovo nome appena si fa clic sul 
pulsante OK. 

Specifica dei dati da visualizzare 



Esistono molti modi per specificare quali dati sono rappresentati da un dataset 
unidirezionale. II metodo scelto dipende dal tipo di dataset unidirezionale utilizzato 
e dal fatto che le informazioni provengano da una singola tabella di database oppure 
siano il risultato di una query o di una procedura registrata. 

Quando si opera con un componente TSQLDataSet, utilizzare la proprieta 
CommandType per indicare da dove il dataset ottiene i dati. CommandType pud 
assumere uno dei seguenti valori: 

• ctQuery: Se CommandType e ctQuery, TSQLDataSet esegue la query che e stata 
specifica. Se la query e un comando SELECT, il dataset contiene il set di record 
risultante. 

• ctTable: Se CommandType e ctTable, TSQLDataSet ricerca tutti i record da una tabella 
specificata. 

• ctStoredProc: Se CommandType e ctStoredProc, TSQLDataSet esegue una procedura 
registrata. Se la procedura registrata restituisce un cursor, il dataset contiene i 
record restituiti. 

possibile anche riempire il dataset unidirezionale con i metadati relativi a tutto cio 
che e disponibile sul server. Per informazioni sull'operazione, vedere "Prelievo di 
metadati in un dataset unidirezionale" a pagina 26-13. 

Rappresentazione dei risultati di una query 



L'utilizzo di una query e il metodo piu generale per specificare un set di record. Le 
query sono semplicemente comandi scritti in SQL. Per rappresentare il risultato di 
una query e possibile utilizzare TSQLDataSet oppure TSQLQuery. 

Quando si utilizza TSQLDataSet, impostare la proprieta CommandType a ctQuery e 
assegnare il testo dell'istruzione query alia proprieta CommandText. Quando si 
utilizza TSQLQuery, assegnare invece la query alia proprieta SQL. Queste proprieta 
funzionano alio stesso modo per tutti dataset di uso generale o di tipo query. Sono 
trattate in maggior dettaglio nel paragrafo. "Specifica della query" a pagina 22-44. 

Quando si specifica la query, si possono includere parametri, o variabili, i cui valori 
possono essere modificati in progettazione o in esecuzione. I parametri possono 
sostituire i valori dei dati che appaiono nell'istruzione SQL. L'utilizzo di parametri 
nelle query e la fornitura di valori per quei parametri e trattato in "Utilizzo dei 
parametri nelle query" a pagina 22-46. 
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SQL definisce query che eseguono azioni sul server ma che non restituiscono record, 
come query di tipo UPDATE. Queste query sono trattate in "Esecuzione di comandi 
che non restituiscono record" a pagina 26-9. 

Rappresentazione dei record in una tabella 



Quando si devono rappresentare tutti i campi e tutti i record di una singola tabella di 
un database sottostante, invece di scrivere personalmente il codice SQL, per generare 
automaticamente la query e possibile utilizzare TSQLDataSet oppure TSQLTable. 

Se le prestazioni del server possono essere un problema, si potrebbe comporre la 
query in modo esplicito invece di affidarsi a una query generata in automatico. 
Invece di elencare esplicitamente tutti i campi della tabella, le query generate in 
automatico utilizzano il carattere jolly. Questo comportamento causa sul server 
prestazioni leggermente piu lente. L'utilizzo del carattere jolly (*) nelle query 
generate in automatico e piu affidabile rispetto alia modifica dei campi sul server. 

Rappresentazione di una tabella mediante TSQLDataSet 

Per fare in modo che TSQLDataSet generi una query che recupera tutti i campi e tutti 
i record di una singola tabella di database, impostare la proprieta CommandType a 
ctTable. 

Se si imposta CommandType a ctTable, TSQLDataSet genera una query in base ai valori 
di due proprieta: 

• CommandText che specifica il nome della tabella di database che l'oggetto 
TSQLDataSet dovrebbe rappresentare. 

• SortFieldNames che elenca i nomi di tutti i campi utilizzati per l'ordinamento dei 
dati, in ordine di importanza. 

Ad esempio, se si specifica quanto segue: 

SQLDataSetl->CommandType = ctTable; 
SQLDataSetl->CommandText = "Employee"; 
SQLDataSetl->SortFieldNames = "HireDate, Salary" 

TSQLDataSet genera la seguente query, che elenca tutti i record nella tabella 
Employee, ordinati per HireDate e, all'interno di HireDate, ordinati per Salary: 

select * from Employee order by HireDate, Salary 

Rappresentazione di una tabella mediante TSQLTable 

Se si utilizza TSQLTable, specificare la tabella desiderata utilizzando la proprieta 

TableName. 

Per specificare l'ordine dei campi nel dataset, e necessario specificare un indice. E 
possibile farlo in due modi: 

• Impostando la proprieta IndexName al nome di un indice definito sul server che 
imponga l'ordine desiderata. 
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• Impostando la proprieta IndexFieldNames a una lista di nomi di campo, delimitata 
con caratteri punto e virgola, in base ai quali eseguire l'ordinamento. 
IndexFieldNames funziona come la proprieta SortFieldNamesdi TSQLDataSet, 
tranne per il fatto che utilizza come delimitatore un punto e virgola invece di una 
virgola. 

Rappresentazione dei risultati di una procedura registrata 



Le procedure registrate sono set di istruzioni SQL a cui e stato assegnato un nome e 
che e stato memorizzato su un server SQL. II modo per indicare la procedura 
registrata che si desidera eseguire dipende dal tipo di dataset unidirezionale 
utilizzato. 

Se si utilizza TSQLDataSet, per specificare una procedura registrata si deve: 

• Impostare la proprieta CommandType a ctStoredProc. 

• Specificare il nome della procedura registrata come valore della proprieta 

CommandText: 

SQLDataSetl->CommandType = CtStoredProc; 
SQLDataSetl->CommandText = "MyStoredProcName" ; 

Se si utilizza TSQLStoredProc , e necessario specificare solo il nome della procedura 
registrata come valore della proprieta StoredProcName. 

SQLStoredProcl->StoredProcName = "MyStoredProcName"; 

Dopo avere identificato una procedura registrata, l'applicazione potrebbe dover 
immettere dei valori per tutti i parametro di input della procedura registrata o 
recuperare i valori dei parametri di output dopo che si e eseguita la procedura 
registrata. Per informazioni sulle operazioni con i parametri delle procedure 
registrate, consultare "Operazioni con i parametri delle procedure registrate" a 
pagina 22-53. 

Reperimento dei dati 



Una volta specificata la sorgente dei dati, prima che l'applicazione possa accedere ai 
dati e necessario ottenerli dal server. Una volta che il dataset ha ottenuto i dati, i 
controlli associati ai dati collegati al dataset tramite una sorgente dati 
visualizzeranno automaticamente i valori dei dati, e sara possibile riempire i dataset 
client, collegati al dataset tramite un provider, con i record. 

Come con qualsiasi altro dataset, esistono due modi per ottenere i dati per un dataset 
unidirezionale: 

• Impostare la proprieta Active a true, nell'Object Inspector in fase di progettazione 
oppure nel codice in fase di esecuzione: 

CustQuery->Active = true; 

• Chiamare il metodo Open in fase di esecuzione: 

CustQuery->Open() ; 
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Utilizzare la proprieta Active o il metodo Open con qualsiasi dataset unidirezionale 
che ottenga i record dal server. Non ha importanza se questi record derivano da una 
query SELECT (incluse le query generate in automatico nel caso in cui CommandType 
sia impostato ctTable) o da una procedura registrata. 

Preparazione del dataset 



Affinche una query o una procedura registrata possa essere eseguita sul server, e 
necessario prima "prepararla". Preparare il dataset significa che dbExpress e il server 
devono allocare risorse per l'istruzione e per i relativi parametri. Se CommandType e 
impostata a ctTable, questo e il momento in cui il dataset genera la query SELECT. A 
questo punto, tutti i parametri che sono scollegati dal server vengono inglobati in 
una query. 

I dataset unidirezionali vengono preparati automaticamente quando si imposta 
Active a true o si chiama il metodo Open. Quando si chiude il dataset, le risorse 
allocate per l'esecuzione dell'istruzione vengono liberate. Se si pensa di eseguire la 
query o la procedura registrata piu di una volta, e possibile migliorare le prestazioni 
preparando esplicitamente il dataset prima di aprirlo per la prima volta. Per 
preparare esplicitamente un dataset, impostare la proprieta Prepared del dataset a 
true. 

CustQuery->Prepared = true; 

Quando si prepara esplicitamente il dataset, le risorse allocate per l'esecuzione 
dell'istruzione non vengono liberate finche non si imposta Prepared a false. 

Impostare la proprieta Prepared a false se si desidera essere certi che il dataset venga 
preparato di nuovo prima dell'esecuzione (ad esempio, se si modifica un valore di 
parametro o la proprieta SortFieldNames). 

Reperimento di piu dataset 



Alcune procedure registrate restituiscono piu set di record.Appena lo si apre, il 
dataset recupera solo il primo set. Per accedere agli altri set di record, chiamare il 
metodo NextRecordSet: 

TCustomSQLDataSet *DataSet2 = SQLStoredProcl->NextRecordSet (nRows) ; 

NextRecordSet restituisce un componente TCustomSQLDataSet creato ex novo che 
consente l'accesso al successivo set di record. Vale a dire, la prima volta che si chiama 
NextRecordSet, il metodo restituisce un dataset per il secondo set di record.La 
successiva chiamata a NextRecordSet restituisce un terzo dataset e cosi via, finche non 
vi sono piu altri set di record. Quando non vi sono piu altri dataset, NextRecordSet 
restituisce NULL. 

Esecuzione di comandi che non restituiscono record 



E possibile utilizzare un dataset unidirezionale anche se la query o la procedura 
registrata che esso rappresenta non restituisce alcun record. Tali comandi includono 
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istruzioni di tipo DDL (Data Definition Language) o DML (Data Manipulation 
Language) diverse da istruzioni SELECT (ad esempio, i comandi INSERT, DELETE, 
UPDATE, CREATE INDEX e ALTER TABLE non restituiscono alcun record). II 
linguaggio utilizzato nei comandi e specif ico del server, ma di solito conforme alio 
standard SQL-92 per il linguaggio SQL. 

II comando SQL che si esegue deve essere conforme alle specifiche del server 
utilizzato. I dataset unidirezionali non sono in grado ne di valutare ne di eseguire 
l'istruzione SQL. Essi si limitano solo a passare il comando al server affinche venga 
eseguito. 

Se il comando non restituisce alcun record, non e affatto necessario utilizzare un 
dataset unidirezionale, in quanto non c'e alcuna necessita di utilizzare i metodi del 
dataset per accedere a un set di record. II componente SQL connection che si collega 
al server di database puo essere utilizzato per eseguire direttamente un comando sul 
server. Per maggiori informazioni, consultare "Invio di comandi al server" a 
pagina 21-11. 

Specifica del comando da eseguire 



Con i dataset unidirezionali esiste un solo modo per specificare il comando da 
eseguire, indipendentemente dal fatto che il comando restituisca o meno un dataset. 
Vale a dire: 

Se si utilizza TSQLDataSet, utilizzare le proprieta CommandType e CommandText per 
specificare il comando: 

• Se CommandType e ctQuery, CommandText e l'istruzione SQL da passare al server. 

• Se CommandType e ctStoredProc, CommandText e il nome della procedura registrata 
da eseguire. 

Se si utilizza TSQLQuery, utilizzare la proprieta SQL per specificare l'istruzione SQL 
da passare al server. 

Se si utilizza TSQLStoredProc, utilizzare la proprieta StoredProcName per specificare il 
nome della procedura registrata da eseguire. 

Dato che si specifica il comando in modo analogo a quanto si fa per reperire i record, 
si operera con i parametri della query o della procedura registrata in un modo 
analogo a quello usato con le query e con le procedure registrate che restituiscono 
record. Per maggiori informazioni, consultare "Utilizzo dei parametri nelle query" a 
pagina 22-46 e "Operazioni con i parametri delle procedure registrate" a 
pagina 22-53. 

Esecuzione del comando 



Per eseguire una query o una procedura registrata che non restituisce alcun record, 
non si utilizza la proprieta Active o il metodo Open. Si deve invece utilizzare 

• II metodo ExecSQL se il dataset e un'istanza di TSQLDataSet o di TSQLQuery. 

FixTicket->CommandText = " DELETE FROM Traf f icViolations WHERE (TicketID = 1099)"; 
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FixTicket->ExecSQL() ; 
• II metodo ExecProc se il dataset e un'istanza di TSQLStoredProc. 

SQLStoredProcl->StoredProcName = "MyCommandWithMoResults 11 ; 
SQLStoredProcl->ExecProc ( ) ; 

Se si esegue piu volte la query o la procedura registrata, e conveniente impostare la 
proprieta Prepared a true. 

Creazione e modifica dei metadati del server 



Quasi tutti i comandi che non restituiscono dati rientrano in due categorie: comandi 
che di solito si utilizzano per modificare i dati (come i comandi INSERT, DELETE e 
UPDATE) e comandi che di solito vengono utilizzati per creare o modificare le entita 
sul server, come tabelle, indici e procedure registrate. 

Se non si vogliono utilizzare comandi SQL espliciti per l'editing, e possibile collegare 
il dataset unidirezionale a un dataset client e lasciare che sia il dataset a gestire la 
generazione di tutti i comandi SQL relativi all'editing (vedere "Connessione di un 
dataset client a un altro dataset nella stessa applicazione" a pagina 18-12). Infatti, 
questo e l'approccio consigliato dal momento che i controlli associati ai dati sono 
progettati per eseguire l'editing tramite un dataset come TCHentDataSet. 

L'unico modo che ha l'applicazione per creare o modificare i metadati sul server, 
tuttavia, e quello di inviare un comando. Non tutti i driver di database supportano la 
stessa sintassi SQL. La descrizione della sintassi SQL supportata da ogni tipo di 
database e delle differenze fra i tipi di database travalica lo scopo di questo manuale. 
Per una discussione completa e aggiornata dell'implementazione SQL per un 
determinato sistema di database, consultare la documentazione fornita con quel 
sistema. 

Di solito, si utilizza l'istruzione CREATE TABLE per creare le tabelle in un database e 
l'istruzione CREATE INDEX per creare nuovi indici per quelle tabelle. Se supportate, 
si possono utilizzare altre istruzioni CREATE per aggiungere diversi oggetti 
metadati, come CREATE DOMAIN, CREATE VIEW, CREATE SCHEMA e CREATE 
PROCEDURE. 

Per ognuna delle istruzioni CREATE, esiste un'istruzione DROP corrispondente per 
cancellare l'oggetto metadati. Queste istruzioni includono DROP TABLE, DROP 
VIEW, DROP DOMAIN, DROP SCHEMA e DROP PROCEDURE. 

Per modificare la struttura di una tabella, utilizzare l'istruzione ALTER TABLE. 
ALTER TABLE ha clausole ADD e DROP per creare nuovi elementi in una tabella e 
per cancellarli. Ad esempio, utilizzare la clausola ADD COLUMN per aggiungere 
alia tabella una nuova colonna e DROP CONSTRAINT per cancellare dalla tabella un 
vincolo esistente. 

Ad esempio, la seguente istruzione crea una procedura registrata di nome 
GET_EMP_PROJ in un database InterBase: 

CREATE PROCEDURE GET_EMP_PROU (EMPJTO SMALLINT) 

RETURNS (PR0J_ID CHAR(5) ) 

AS 
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BEGIN 

FOR SELECT PR0J_ID 
FROM EMPLOYEE_PROJECT 
WHERE EMP_N0 = :EMP_N0 
INTO :PR0J_ID 
DO 

SUSPEND; 

END 

II codice seguente utilizza un TSQLDataSet per creare questa procedura registrata. Si 
noti dell'utilizzo della proprieta ParamCheck per impedire al dataset di confondere i 
parametri nella definizione della procedura registrata (:EMP_NO e :PROJ_ID) con un 
parametro della query che crea la procedura registrata. 

SQLDataSetl->ParamCheck = false; 
SQLDataSetl->CommandType = ctQuery; 

SQLDataSetl->CommandText = "CREATE PROCEDURE GET_EMP_PROJ (EMP_N0 SMALLINT) RETURNS (PR0J_ID 
CHAR ( 5 ) ) AS BEGIN FOR SELECT PR0J_ID FROM EMPLOYEE_PROJECT WHERE EMP_N0 = : EMP_N0 INTO 
:PR0J_ID DO SUSPEND; END"; 
SQLDataSetl->ExecSQL() ; 

Configurazione di cursor master/detail collegati 



Esistono due modi per utilizzare cursor collegati al fine di impostare una relazione 
master /detail che utilizza un dataset unidirezionale per il set di dettaglio. II metodo 
utilizzato dipende dal tipo di dataset unidirezionale che si utilizza. Una volta 
impostata tale relazione, il dataset unidirezionale (la parte "molti" in una relazione 
uno-a-molti) fornisce l'accesso solo a quei record che corrispondono al record 
corrente del set master (la parte "uno" in una relazione uno-a-molti). 

TSQLDataSet e TSQLQuery richiedono che si utilizzi una query con parametri per 
stabilire una relazione master/ detail. Questa e la tecnica per la creazione di tali 
relazioni su tutti i dataset di tipo query. Per i dettagli sulla creazione delle relazioni 
master/ detail con dataset di tipo query, vedere "Impostazione di relazioni master/ 
detail mediante parametri" a pagina 22-49. 

Per impostare una relazione master/ detail dove il set di dettaglio e un'istanza di 
TSQLTable, utilizzare le proprieta MasterSource e MasterFields esattamente come si 
farebbe con qualsiasi altro dataset di tipo tabella. Per i dettagli sulla creazione delle 
relazioni master/ detail con dataset di tipo tabella, vedere "Impostazione di relazioni 
master/ detail mediante parametri" a pagina 22-49. 

Accesso a informazioni di schema 



Esistono due modi per ottenere informazioni su cio che e disponibile sul server. 
Queste informazioni, dette informazioni di schema o metadati, includono 
informazioni su quali tabelle e procedure registrate sono disponibili sul server e 
informazioni su quelle tabelle e su quelle procedure registrate (come i campi 
contenuti in una tabella, gli indici definiti e i parametri utilizzati da una procedura 
registrata). 
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II modo piu semplice per ottenere questi metadati e quello di utilizzare i metodi di 
TSQLConnection. Questi metodi riempiono una lista di stringhe esistente oppure un 
oggetto list con i nomi di tabelle, di procedure registrate, di campi o di indici o con i 
descrittori di parametro. Questa tecnica e analoga a quella utilizzata con tutti gli altri 
componenti di connessione database per riempire le liste con metadati. Questi 
metodi sono descritti in "Ottenimento di metadati" a pagina 21-14. 

Se si richiedono informazioni di schema piu dettagliate, e possibile riempire un 
dataset unidirezionale con metadati. Invece di riempire una semplice lista, il dataset 
unidirezionale vine riempito con le informazioni di schema, in cui ogni record 
rappresenta una singola tabella, una procedura registrata, un indice, un campo o un 
parametro. 

Prelievo di metadati in un dataset unidirezionale 



Per riempire i dataset unidirezionali con i metadati ottenuti dal server di database, e 
necessario prima indicare quali dati si desidera vedere utilizzando il metodo 
SetSchemalnfo. SetSchemalnfo accetta tre parametri: 

• II tipo di informazioni di schema (metadati) che si desidera ottenere. Questo puo 
essere una lista di tabelle (stTables), una lista di tabelle di sistema (stSysTables), una 
lista di procedure registrate (stProcedures), una lista di campi in una tabella 
(stColumns), una lista di indici (stlndexes) o una lista dei parametri utilizzati da una 
procedura registrata (stProcedureParams). Ogni tipo di informazioni utilizza un set 
diverso di campi per descrivere gli elementi nella lista. Per i dettagli sulle strutture 
di questi dataset, vedere "La struttura dei dataset di metadati" a pagina 26-14. 

• Se si vogliono ottenere informazioni su campi, indici o parametri di una procedura 
registrata, il nome della tabella o della procedura registrata a cui tali informazioni 
si applicano. Se si vogliono ottenere altri tipi di informazioni di schema, questo 
parametro e NULL. 

• Un modello che deve trovare una corrispondenza per ogni nome restituito. Questo 
modello e un modello SQL come 'Cust%', che utilizza i caratteri jolly '%' (che 
corrisponde a una stringa di caratteri arbitrari di qualsiasi lunghezza) e '_' (che 
corrisponde a un singolo carattere arbitrario). Per utilizzare nel modello un 
simbolo percentuale o un carattere di sottolineatura, si deve raddoppiare il 

carattere (%% o ). Se non si desidera utilizzare un modello, questo parametro 

puo essere NULL. 

Se si vogliono ottenere informazioni di schema sulle tabelle (stTables), le informazioni 
di schema risultanti possono descrivere tabelle comuni, tabelle di sistema, viste e/o 
sinonimi, a seconda del valore della proprieta TableScope della connessione SQL. 

La seguente chiamata richiede una tabella che elenca tutte le tabelle di sistema 
(tabelle del server che contengono metadati): 

SQLDataSetl->SetSchemaInfo(stSysTable, "", ""); 

Se si apre il dataset dopo questa chiamata a SetSchemalnfo, il dataset risultante 
contiene un record per ogni tabella, con colonne che riportano il nome di tabella, il 
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tipo, il nome dello schema, e cosi via. Se il server non utilizza tabelle di sistema per 
memorizzare i metadati (ad esempio MySQL), il dataset non conterra alcun record. 

Nell'esempio precedente si e utilizzato solo il primo parametro. Si supponga, invece, 
di voler ottenere una lista di parametri di input per una procedura registrata di nome 
'MyProc'. Si supponga, inoltre, che chi ha scritto quella procedura registrata abbia 
chiamato tutti i parametri utilizzando un prefisso per indicare se erano parametri di 
input o di output ('inName', 'outvalue' e cosi via). In questo caso, si potrebbe 
chiamare SetSchemalnfo in questo modo: 

SQLDataSetl->SetSchemaInfo (stProcedureParams, "MyProc", "in*") ; 

II dataset risultante e una tabella di parametri di input con colonne che descrivono le 
proprieta di ogni parametro. 

Ottenimento dei dati dopo aver utilizzato il dataset per i metadati 

Dopo aver effettuato una chiamata a SetSchemalnfo, esistono due modi per ritornare 
con il dataset alle query o alle procedure registrate in esecuzione: 

• Modificare la proprieta CommandText, specificando la query, la tabella o la 
procedura registrata da cui si desidera ottenere i dati. 

• Chiamare SetSchemalnfo, impostando il primo parametro a stNoSchema. In questo 
caso, il dataset ritorna a prendere i dati specificati dal valore corrente di 
CommandText. 

La struttura dei dataset di metadati 

Per ogni tipo di metadati a cui e possibile accedere utilizzando TSQLDataSet, esiste 
un insieme predefinito di colonne (campi) che viene compilato con le informazioni 
sugli elementi del tipo richiesto. 

Informazioni sulle tabelle 

Quando si richiedono informazioni sulle tabelle (stTables o stSysTables), il dataset 
risultante include un record per ciascuna tabella. Ha le seguenti colonne: 

Tabella 26.1 Colonne nelle tabelle di metadati che elencano tabelle 
Tipo di 

Nome della colonna campo Contenuto 

RECNO ftlnteger Un numero di record che identifica in modo univocamente 

ciascun record. 

CATALOG_NAME ftString II nome del catalogo (database) che contiene la tabella. E 

analogo al parametro Database di un componente connection 
SQL. 

SCHEMA_NAME ftString II nome dello schema che identifica il proprietario della 

tabella. 
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Tabella 26.1 Colonne nelle tabelle di metadati che elencano tabelle 



Nome della colonna 


Tipo di 
campo 


Contenuto 


T A T2T T7 XT A "N /TT7 


ftString 


11 nome della tabella. Questo campo determina la sequenza di 






ordinamento del dataset. 


TABLE_TYPE 


ftlnteger 


Identifica il tipo di tabella. E la somma di uno o piu dei 






seguenti valori: 






1: Tabella 






2: Vista 






4: Tabella di sistema 






8: Sinonimo 






16: Tabella temporanea 






32: Tabella locale. 



Informazioni sulle procedure registrate 

Quando si richiedono informazioni sulle procedure registrate (stProcedures), il 
dataset risultante include un record per ogni procedura registrata. Ha le seguenti 
colonne: 



Tabella 26.2 Colonne nelle tabelle di metadati che elencano procedure registrate 



Tipo di 

Nome della colonna campo Contenuto 



RECNO 


ftlnteger 


Un numero di record che identifica in modo univocamente 
ciascun record. 


CATALOGJVAME 


ftString 


11 nome del catalogo (database) che contiene la procedura 
registrata. E analogo al parametro Database di un componente 
connection SQL. 


SCHEMA_NAME 


ftString 


11 nome dello schema che identifica il proprietario della 
procedura registrata. 


PROC_NAME 


ftString 


11 nome della procedura registrata. Questo campo determina la 
sequenza di ordinamento del dataset. 


PROC.TYPE 


ftlnteger 


Identifica il tipo di procedura registrata. E la somma di uno o 
piu dei seguenti valori: 

1: Procedura (nessun valore restituito) 

2: Funzione (restituisce un valore) 

4: Package 

8: Procedura di sistema 


IN_P ARAMS 


ftSmallint 


11 numero di parametri di input 


OUT_PARAMS 


ftSmallint 


11 numero di parametri di output. 
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Informazioni sui campi 

Quando si richiedono informazioni sui campi in una tabella specificata (stColumns), il 
dataset risultante include un record per ciascun campo. Include le seguenti colonne: 



Tabella 26.3 Colonne nelle tabelle di metadati che elencano campi 







Tlpo di 




Nome della colonna 


campo 


Contenuto 


RECNO 




ftlnteger 


Un numero di record che identifica in modo 






univocamente ciascun record. 


CATALOGJMAME 


ftString 


11 nome del catalogo (database) che contiene la tabella di 








cui si stanno elencando i campi. E analogo al parametro 








Database di un componente connection SQL. 


SCHEMAJVAME 


ftString 


11 nome dello schema che identifica il proprietario del 








campo. 


TABLEJVAME 


ftStrine 

1 Lk^y LI 11 LZL 


Tl nomp Hplla tobplla rbp rontipnp i ramni 


COLUMN 


.NAME 


ftString 


11 nome del campo. Questo valore determina la sequenza 

Hi otH in 3 ttipti to HpI Hiit^iGP'H 
HI (JlUllLctlllfcrllLL' Ufcrl Lid. LclSc L. 


COLUMN 


.POSITION 


ftSmallint 


La posizione della colonna nella rispettiva tabella. 


TOT T IMN 

V- v_ ' 1 - l_J 1V11N_ 


TYPE 


ftlnteger 


Identifica il tipo di valore nel campo. E la somma di uno o 
piu dei seguenti valori: 

1: Identificativo della riga 

2: Versione della riga 

8: Campo con valore predefinito 


COLUMN 


DATATYPE 


ftSmallint 


11 tipo di dati della colonna. Questa e una delle costanti 

1 /~\m n a /Hi \"l V\ t~\ ri 1 /H /Hot! 1 4"£> in c 1 M is*C 

KJiilLIlfc; Lll L1UU llclU Qcllllllc III aLIlllIliS.D.IL. 


COLUMN 


TYPENAME 


ftString 


Una stringa che descrive il tipo di dati. Queste sono le 

cfpccp informa 7inni rntifpnutp in C^OT T TTvTTXT OAXAXYPP 

JLCJOC 11 LI v/1 11 LdZ-iLKJl LI v. K-'L ILvll LI LC 11 L V— V__/ L/ 1V11 \ I s J \ I 1 V 1 11 lj 

e in COLUMN_SUBTYPE, ma nel formato utilizzato in 
alcune istruzioni DDL. 


COLUMN 


.SUBTYPE 


ftSmallint 


Un sottotipo per il tipo di dati della colonna. Questa e una 
delle costanti logiche di tipo subtype definite in sqllinks.h. 


COLUMN 


PRECISION 


ftlnteger 


La dimensione del tipo di campo (numero di caratteri in 
una stringa, byte in uno campo Byte, cifre significative in 
un valore BCD, membri di un campo ADT, e cosi via). 


COLUMN 


.SCALE 


ftSmallint 


11 numero di cifre alia destra della virgola per valori BCD, 
o discendenti su ADT e campi array. 


COLUMN 


LENGTH 


ftlnteger 


11 numero di byte richiesti per memorizzare i valori del 
campo. 


COLUMN 


NULLABLE 


ftSmallint 


Un Boolean che indica se il campo pud essere lasciato in 
bianco (0 significa che il campo richiede un valore). 



Informazioni sugli indici 

Quando si richiedono informazioni sugli indici su una tabella (stlndexes), il dataset 
risultante include un record per ogni campo in ciascun record. (Gli indici multi- 
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record vengono descritti utilizzando piu record) :Tabella 26.4 Colonne nelle tabelle di 
metadati che elencano indici: 



Tabella 26.4 Colonne nelle tabelle di metadati che elencano indici 
Tipo di 

campo Contenuto 

ftlnteger 



Nome della colonna 



RECNO 
CATALOG_NAME 

SCHEMA_NAME 

TABLE_NAME 
INDEX_NAME 

PKEYJVAME 
COLUMN_NAME 
COLUMN_POSITION 
INDEX TYPE 



SORT_ORDER 
FILTER 



Un numero di record che identifica in modo univocamente 
ciascun record. 

ftString II nome del catalogo (database) che contiene l'indice. E 
analogo al parametro Database di un componente 
connection SQL. 

ftString II nome dello schema che identifica il proprietario 
dell'mdice. 

ftString II nome della tabella per cui l'indice e definito. 

ftString II nome dell'mdice. Questo campo determina la sequenza di 
ordinamento del dataset. 

ftString Indica il nome della chiave primaria. 

ftString II nome del campo (colonna) nell'indice. 

ftSmallint La posizione di questo campo nell'indice. 

ftSmallint Identifica il tipo di indice. E la somma di uno o piu dei 
seguenti valori: 
1: Non-univoco 
2: Univoco 
4: Chiave primaria 

ftString Indica che l'indice e ascendente (a) o discendente (d). 

ftString Descrive una condizione di filtro che limita i record 
indicizzati. 



Informazioni sui parametri delle procedure registrate 

Quando si richiedono informazioni sui parametri di una procedura registrata 
(stProcedureParams), il dataset risultante include un record per ogni parametro. Ha le 
seguenti colonne: 

Tabella 26.5 Colonne nelle tabelle di metadati che elencano parametri 



Nome della 

RECNO 



Tipo di 
campo 

ftlnteger 



CATALOGJSfAME ftString 

SCHEMA_NAME ftString 

PROC_NAME ftString 

PARAMJMAME ftString 



Contenuto 

Un numero di record che identifica in modo univocamente 
ciascun record. 

II nome del catalogo (database) che contiene la procedura 
registrata. E analogo al parametro Database di un 
componente connection SQL. 

II nome dello schema che identifica il proprietario della 
procedura registrata. 

II nome della procedura registrata che contiene il 
parametro. 

II nome del parametro. Questo campo determina la 
sequenza di ordinamento del dataset. 
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Tabella 26.5 Colonne nelle tabelle di metadati che elencano parametri 







Tipo di 




Nome della colonna 


campo 


Contenuto 


PARAM. 


TYPE 


ftSmallint 


Identifica il tipo di parametro. E analogo alia proprieta 
ParamType di un oggetto TParam. 


PARAM. 


.DATATYPE 


ftSmallint 


11 tipo di dati del parametro. Questa e una delle costanti 
logiche di tipo field definite in sqllinks.h. 


PARAM. 


.SUBTYPE 


ftSmallint 


T Tn Q(~vH oil no nor il tino Hi Hati HpI t*i aram ptm Oi i pcta p una 

l_J ± L O \J l LU LI VJ \J UCl 11 L1L/U \-ll \-lCl Li Llcl LJtll all LC LI \J . K^S LlCO LCI C Lll LCI 

delle costanti logiche di tipo subtype definite in sqllinks.h. 


PARAM. 


.TYPENAME 


ftString 


Una stringa che descrive il tipo di dati. Queste sono le stesse 
informazioni contenute in PARAM_DATATYPE e in 
PARAM_SUBTYPE, ma in un formato utilizzato in alcune 
istruzioni DDL. 


PARAM 

1 AlullVl 


PRFCTSTON 


ftlnteger 


11 numero massimo di cifre nei valori a virgola mobile o di 






byte (per stringhe e campi Bytes). 


PARAM. 


.SCALE 


ftSmallint 


11 numero di cifre alia destra della virgola in valori a virgola 
mobile. 


PARAM. 


LENGTH 


ftlnteger 


11 numero di byte richiesti per memorizzare i valori del 
parametro. 


PARAM. 


.NULLABLE 


ftSmallint 


Un Boolean che indica se il parametro puo essere lasciato in 
bianco (0 significa che il parametro richiede un valore). 
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Mentre si esegue il debug dell'applicazione database, potrebbe rivelarsi utile 
controllare i messaggi SQL che vengono inviati e ricevuti dal server di database 
attraverso il componente connection, inclusi quelli generati automaticamente (ad 
esempio da un componente provider o dal driver dbExpress). 

Utilizzo di TSQLMonitor per controllare i comandi SQL 



TSQLConnection utilizza un componente di appoggio, TSQLMonitor, per intercettare 
questi messaggi e salvarli in una lista di stringhe. TSQLMonitor opera in modo simile 
al programma di utilita SQL monitor che e possibile utilizzare con BDE, tranne per il 
fatto che controlla solo quei comandi che implicano un singolo componente 
TSQLConnection invece di tutti i comandi gestiti da dbExpress. 

Per utilizzare TSQLMonitor: 

1 Aggiungere un componente TSQLMonitor alia scheda o al modulo dati che 
contiene il componente TSQLConnection di cui si desidera controllare i comandi 
SQL. 

2 Impostare la proprieta SQLConnection al componente TSQLConnection. 

3 Impostare la proprieta Active di SQL monitor a true. 
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Man mano che i comandi SQL vengono inviati al server, la proprieta TraceList di SQL 
monitor viene aggiornata automaticamente elencando tutti i comandi SQL 
intercettati. 

E possibile salvare questa lista in un file specificando un valore per la proprieta 
FileName e quindi impostando la proprieta AutoSave a true. AutoSave fa in modo che 
SQL monitor salvi in un file il contenuto della proprieta TraceList ogni volta che 
intercetta un nuovo messaggio. 

Se non si desidera l'appesantimento dovuto al salvataggio del file ogni volta che 
viene intercettato un messaggio, e possibile utilizzare il gestore di evento OnLogTrace 
per salvare il file solo dopo l'intercettazione di vari messaggi. Ad esempio, il 
seguente gestore di evento salva il contenuto di TraceList ogni 10 messaggi, 
cancellando il file di registrazione dopo averlo salvato in modo che la lista non 
divenga mai troppo lunga: 

void __fastcall TForml: :SQLMonitorlLogTrace(TObject *Sender, void *CBInfo) 
{ 

TSQLMonitor *pMonitor = dynamic_cast<TSQLMonitor *> (Sender) ; 
if (pMonitor->TraceCount == 10) 

{ 

// build unique file name 

AnsiStrmg LogFileName = "c:\Uog"; 

LogFileName = LogFileName + IntToStr(pMonitor->Tag) ; 

LogFileName = LogFileName + ".txt" 

pMonitor->Tag = pMonitor->Tag + 1; 

// Save contents of log and clear the list 

pMonitor->SaveToFile (LogFileName) ; 

pMonitor->TraceList->Clear ( ) ; 

} 

Se si decidesse di utilizzare il gestore di evento precedente, alia chiusura 
dell'applicazione sarebbe necessario salvare anche una eventuale lista parziale 
(contenente meno di 10 voci. 

Utilizzo di una callback per controllare i comandi SQL 



Invece di utilizzare TSQLMonitor, e possibile personalizzare il modo in cui 
l'applicazione tiene traccia dei comandi SQL utilizzando il metodo 
SetTraceCallbackEvent del componente SQL connection. SetTraceCallbackEvent accetta 
due parametri: una callback di tipo TSQLCallbackEvent e un valore definito 
dall'utente che viene passato alia funzione callback. 

La funzione callback accetta due parametri: CallType e CBInfo: 

• CallType e un parametro riservato per un successivo utilizzo. 

• CBInfo e un puntatore a un structure che include la categoria (la stessa di CallType), 
il testo del comando SQL e il valore definito dall'utente che viene passato al 
metodo SetTraceCallbackEvent. 
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La callback restituisce un valore di tipo CBRType, di solito cbrlISEDEF.il driver 
dbExpress chiama la callback ogni volta che il componente SQL connection passa un 
comando al server o il server restituisce un messaggio di errore. 

Non chiamare SetTraceCallbackEvent se all'oggetto TSQLConnection e associato un 
componente TSQLMonitor. TSQLMonitor utilizza il meccanismo di callback per 
operare e TSQLConnection puo supportare una sola callback per volta. 
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I dataset client sono dataset specializzati che conservano tutti i propri dati in 
memoria. II supporto per il trattamento dei dati che essi memorizzano in memoria e 
fomito da midas.dll. II formato utilizzato dai dataset client per la memorizzazione di 
dati e indipendente ed e facilmente trasportabile, il che consente ai dataset client di 

• Leggere e scrivere in file dedicati su disco, agendo come un dataset basato su file. 
Le proprieta e i metodi che supportano questo meccanismo sono descritti in "Uso 
di un dataset client con dati basati su file" a pagina 27-35. 

• Memorizzare in cache gli aggiornamenti per i dati provenienti da un server di 
database. Le funzioni dei dataset client che supportano gli aggiornamenti in cache 
sono descritte in "Utilizzo di un dataset client per registrare in cache gli 
aggiornamenti" a pagina 27-17. 

• Rappresentare i dati nella parte client di un'applicazione multi-tier. Per funzionare 
in questo modo, il dataset client deve operare con un provider esterno, come 
descritto in "Uso di un dataset client con un provider di dati" a pagina 27-26. Per 
informazioni sulle applicazioni database multi-tier, consultare il Capitolo 29, 
"Creazione di applicazioni multi-tier". 

• Rappresentare i dati da una sorgente diversa da un dataset. Poiche un dataset 
client puo utilizzare i dati provenienti da un provider esterno, i provider 
specializzati possono adattare una varieta di fonti di informazioni per operare con 
i dataset client. Ad esempio, e possibile utilizzare un provider XML per consentire 
a un dataset client di rappresentare le informazioni contenute in un documento 
XML. 

Sia che si utilizzino i dataset client per dati basati su file, per memorizzare in cache gli 
aggiornamenti, per dati provenienti da un provider esterno (come nel caso di 
operazioni con un documento XML o in un'applicazione multi-tier) o per una 
combinazione di questi approcci come nel caso di un'applicazione "modello 
briefcase", e possibile sfruttare i vantaggi offerti dalla vasta gamma di funzioni 
supportate dai dataset client per operare con i dati. 
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Come si fa con qualunque dataset, e possibile utilizzare i dataset client per fornire i 
dati per i controlli associati ai dati ricorrendo a un componente sorgente dati. Per 
informazioni su come visualizzare i dati del database nei controlli data-aware, 
consultare il Capitolo 19, "Uso dei controlli dati". 

I dataset client implementano tutte le proprieta e i metodi ereditati da TDataSet. Per 
una presentazione completa di questo comportamento generico dei dataset, 
consultare il Capitolo 22, "I dataset". 

Inoltre, i dataset client implementano molte delle f unzioni comuni ai dataset di tipo 
tabella come: 

• Ordinamento dei record con indici. 

• Utilizzo di indici per la ricerca di record. 

• Limitazione dei record con gli intervalli. 

• Creazione di relazioni master / detail. 

• Controllo dell'accesso in lettura/ scrittura 

• Creazione del dataset sottostante 

• Svuotamento del dataset 

• Sincronizzazione dei dataset client 

Per i dettagli relativi a queste funzioni, consultare "Utilizzo dei dataset di tipo tabella' 
a pagina 22-26. 

I dataset client differiscono dagli altri dataset in quanto mantengono tutti i loro dati 
in memoria. Pertanto, il loro supporto per alcune funzioni di database possono 
comportare ulteriori capacita o considerazioni. Questo capitolo descrive alcune di 
queste funzioni comuni e le differenze introdotte dai dataset client. 

Come spostarsi tra i dati nei dataset client 



Se un'applicazione utilizza controlli associati ai dati standard, un utente puo 
spostarsi tra i record di un dataset client usando il comportamento nativo di questi 
controlli. E possibile spostarsi tra i record da programma utilizzando i metodi 
standard dei dataset, quali First, Last, Next e Prior. Per ulteriori informazioni su questi 
metodi, consultare "Spostamenti nei dataset" a pagina 22-5. 

Diversamente dalla maggior parte dei dataset, i dataset client possono anche 
posizionare il cursore su un record specifico del dataset utilizzando la proprieta 
RecNo. Generalmente, un'applicazione usa RecNo per determinare il numero di 
record del record attivo. I dataset client possono, tuttavia, impostare RecNo a un 
particolare numero di record per far si che quel record diventi attivo. 

Come limitare i record da visualizzare 



To Per limitare temporaneamente l'accesso da parte degli utenti a un sottogruppo di 
dati disponibili, le applicazioni possono utilizzare gli intervalli e i filtri. Quando si 
applica un intervallo o un filtro, il dataset client non visualizza tutti i dati presenti 
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nella sua memoria cache. Mostra, invece, solo i dati che soddisfano le condizioni 
deU'intervallo o del filtro. Per ulteriori informazioni sull'utilizzo di filtri, consultare 
"Visualizzazione e modifica di un sottoinsieme di dati usando i filtri" a pagina 22-13. 
Per ulteriori informazioni sugli intervalli, consultare "Limitazione dei record con gli 
intervalli" a pagina 22-32. 

Con la maggior parte dei dataset le stringhe del filtro vengono suddivise in comandi 
SQL che vengono poi implementati nel database server. Ne deriva che il dialetto SQL 
del server limita le operazioni che possono essere utilizzate nelle stringhe del filtro. I 
dataset client implementano un proprio supporto per i filtri, che include un maggior 
numero di operazioni rispetto agli altri dataset. Per esempio, quando si utilizza un 
dataset client, le espressioni filtro possono includere operatori stringa che 
restituiscono sottostringhe, operatori che suddividono i valori data/ora, ed altro 
ancora. I dataset client consentono, inoltre, l'uso di filtri sui campi BLOB o su tipi di 
campi complessi come i campi ADT e i campi array. 

Nella tabella seguente sono elencati gli operatori e le funzioni che i dataset client 
possono utilizzare nei filtri, oltre a un confronto con altri dataset che supportano 
filtri: 



Tabella 27.1 Supporto per i filtri nei dataset client 



Operatore o 
funzione 


Esempio 


oupponaiu 
dagli altri 
dataset 


Commento 


Confronto 








= 


State = 'CA' 


Si 




<> 


State <> 'CA' 


Si 




>= 


DateEntered >= '1/1/1998' 


Si 




<= 


Total <= 100,000 


Si 




> 


Percentile > 50 


Si 




< 


Fieldl < Field2 


Si 




BLANK 


State <> 'CA' or State = BLANK 


Si 


I record vuoti non 








vengono visualizzati a 








meno che non siano 








esplicitamente inclusi nel 








filtro. 


IS NULL 


Fieldl IS NULL 


No 




IS NOT NULL 


Fieldl IS NOT NULL 


No 




Operatori logici 








and 


State = 'CA' and Country = US' 


Si 




or 


State = 'CA' or State = 'MA' 


Si 




not 


not (State = 'CA') 


Si 




Operatori 








aritmetici 








+ 


Total + 5 > 100 


Dipende dal 


Vale per numeri, stringhe 






driver 


o date (ore) + numero. 



Utilizzo dei dataset client 27-3 



Utilizzo dei dati tramile un dataset client 



Tabella 27.1 Supporto per i filtri nei dataset client (continua) 

Supportato 

Operatore o dagli altri 

funzione Esempio dataset Commento 

Fieldl - 7 <> 10 Dipende dal Vale per numeri, stringhe 

driver o date (ore) - numero. 

* Discount * 100 > 20 Dipende dal Vale solo per numeri. 

driver 

/ Discount > Total / 5 Dipende dal Vale solo per numeri. 

driver 



Funzioni di 
stringa 

Upper 

Lower 

Substring 



Trim 

TrimLeft 
TrimRight 



Upper(Fieldl) = 'ALWAYS' 

Lower(Fieldl + Field2) = 'josp' 

Substring(DateFld,8) = '1998' 
Substring(DateFld,l,3) = 'JAN' 



Trim(Fieldl + Field2) 
Trim(Fieldl, '-') 



TrimLeft(StringField) 
TrimLeft(Fieldl, '$') <> " 

TrimRight(StringField) 
TrimRight(Fieldl, '.') <> " 



No 
No 
No 



No 

No 
No 



II valore va dalla posizione 
del secondo argomento 
fino alia fine o fino al 
numero di caratteri 
specificato nel terzo 
argomento. II primo 
carattere ha la posizione 1. 

Rimuove il terzo 
argomento dalla parte 
iniziale e finale. Se non c'e 
un terzo argomento, 
elimina gli spazi. 

Vedi Trim. 
Vedi Trim. 



Funzioni 
DateTime 

Year 

Month 

Day 

Hour 

Minute 

Second 

GetDate 

Date 

Time 



Year(DateField) = 2000 No 

Month(DateField) <> 12 No 

Day(DateField) = 1 No 

Hour(DateField) < 16 No 

Minute(DateField) = No 

Second(DateField) = 30 No 

GetDate - DateField > 7 No 

DateField = Date(GetDate) No 

TimeField > Time(GetDate) No 



Rappresenta la data e l'ora 
correnti. 

Restituisce la parte data di 
un valore datetime. 

Restituisce la parte ora di 
un valore datetime. 
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Tabella 27.1 Supporto per i filtri nei dataset client (continua) 

Supportato 

Operatore o dagli altri 

funzione Esempio dataset Commento 

Varie 



Like 



In 



Memo LIKE '%filters%' 



Day(DateField) in (1,7) 



No 



No 



Funziona come in SQL -92 
senza la clausola ESC. Se 
applicato a campi BLOB, 
FilterOptions determina se 
viene tenuto conto di 
maiuscole e minuscole. 

Funziona come in SQL-92. 
II secondo argomento e 
una lista di valori tutto 
dello stesso tipo. 

Carattere jolly per 
confronti parziali. 



State = 'M* 



Si 



Quando si applicano intervalli o filtri, il dataset client memorizza anche tutti i suoi 
record in memoria. L'intervallo o il filtro determina semplicemente quali record sono 
disponibili per i controlli che servono per visualizzare o per spostarsi tra i dati del 
dataset client. 

Quando si recuperano dati da un provider e possibile anche limitare i dati 
memorizzati nel dataset client fornendo dei parametri al provider. Per ulteriori 
informazioni, consultare "Limitazione dei record mediante parametri" a 
pagina 27-31. 

Editing di dati 



I dataset client rappresentano i propri dati come un pacchetto dati in memoria. 
Questo pacchetto e il valore della proprieta Data del dataset client. Per impostazione 
predefinita, tuttavia, le modifiche non vengono memorizzate nella proprieta Data. 
Invece, gli inserimenti, le cancellazioni e le modifiche (apportate dagli utenti o da 
programma) vengono memorizzati in un registro interno delle modifiche, 
rappresentato dalla proprieta Delta. L'uso di un registro delle modifiche serve a due 
scopi: 

• II registro delle modifiche e necessario per applicare gli aggiornamenti a un server 
di database o a un componente provider esterno. 

• II registro delle modifiche fornisce un supporto sofisticato per 1'annullamento 
delle modifiche. 

La proprieta LogChanges consente di disattivare temporaneamente la registrazione. 
Quando LogChanges e true, le modifiche vengono memorizzate nel registro. Quando 
e false, le modifiche vengono apportate direttamente alia proprieta Data. E possibile 
disattivare il registro delle modifiche nelle applicazioni basate su file se il supporto 
per rannullamento non e necessario. 
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Le modifiche rimangono nel registro finche non vengono rimosse dall'applicazione. 
Le applicazioni rimuovono le modifiche quando 

• Vengono annullate 

• Vengono salvate 

II salvataggio del dataset client in un file non rimuove le modiche dal registro delle 
modifiche. Quando si ricarica il dataset, le proprieta Data e Delta rimangono 
identiche a com'erano quando i dati sono stati salvati. 

Annullamento delle modifiche 

Anche se la versione originale di un record rimane invariata in Data, ogni volta che 
un utente modifica un record, lo lascia e vi ritorna, l'utente vede la versione 
modificata per ultima di un record. Se un utente o un'applicazione modifica un 
record un certo numero di volte, ogni versione modificata del record viene 
memorizzata nel registro delle modifiche come una voce separata. 

La memorizzazione di ciascuna modifica apportata a un record rende possibile il 
supporto di piu livelli di operazioni di annullamento di quante ne occorrerebbero per 
ripristinare lo stato precedente di un record: 

• Per rimuovere l'ultima modifica apportata a un record, occorre chiamare 
UndoLastChange. UndoLastChange accetta un parametro booleano, FollowChange, 
che indica se riposizionare o no il cursore sul record ripristinato (true), o se 
lasciare il cursore sul record corrente (false). Se a un record sono state apportate 
diverse modifiche, ogni chiamata a UndoLastChange rimuove un livello di 
modifiche. UndoLastChange restituisce un valore booleano che indica la riuscita o 
meno dell'operazione. Se la rimozione ha successo, UndoLastChange restituisce 
true. Per determinare se ci sono ulteriori modifiche da annullare, si deve ricorrere 
alia proprieta ChangeCount. ChangeCount indica il numero di modifiche 
memorizzate nel registro delle modifiche. 

• Anziche rimuovere ogni livello di modifica apportata a un singolo record, e 
possibile rimuoverle tutti contemporaneamente. Per rimuovere tutte le modifiche 
di un record, occorre selezionarlo e chiamare RevertRecord. RevertRecord rimuove 
dal registro delle modifiche tutti i cambiamenti apportati al record attivo. 

• Per ripristinare un record cancellato, per prima cosa impostare la proprieta 
StatusFilter a [usDeleted], il che rende " visibili" i record cancellati. Quindi, 
spostarsi sul record che si desidera ripristinare e chiamare RevertRecord. Infine, 
ripristinare la proprieta StatusFilter a [usModified, uslnserted, usUnmodified] in 
modo che la versione modificata del dataset (ora contenente il record ripristinato) 
sia nuovamente visibile. 

• In qualunque punto durante le modifiche e possibile salvare lo stato attuale del 
registro delle modifiche utilizzando la proprieta SavePoint. La lettura di SavePoint 
restituisce un marcatore nella posizione corrente del registro delle modifiche. In 
seguito, se si vogliono annullare tutte modifiche apportate dopo la lettura del 
punto in cui e stato effettuato il salvataggio, occorre impostare SavePoint al valore 
letto in precedenza. L'applicazione puo ottenere valori per diversi punti di 
salvataggio. Tuttavia, una volta effettuata la copia di riserva del registro delle 
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modifiche in un punto di salvataggio, i valori di tutti i punti di salvataggio letti 
successivamente dall'applicazione non sono validi. 

• Chiamando CancelUpdates, si possono abbandonare tutte le modifiche 
memorizzate nel registro. CancelUpdates azzera il registro delle modifiche, 
rimuovendo di fatto tutte le modifiche apportate ai record. CancelUpdates va, 
pertanto, utilizzato con molta attenzione.Dopo aver chiamato CancelUpdates, non e 
possibile recuperare le modifiche che si trovavano nel registro. 

Salvataggio delle modifiche 

I dataset client utilizzano meccanismi diversi per incorporare le modifiche dal 
registro delle modifiche, a seconda del fatto che i dataset client registrino i propri dati 
in un file rappresentino dei dati ottenuti mediante un provider. Indipendentemente 
dal meccanismo usato, il registro delle modifiche viene svuotato automaticamente 
quando tutti gli aggiornamenti sono stati incorporati. 

Le applicazioni autonome possono semplicemente fondere le modifiche nella cache 
locale rappresentata dalla proprieta Data. Esse non devono preoccuparsi di come 
risolvere i problemi derivanti dalle modifiche locali con quelle apportate da altri 
utenti. Per fondere il registro delle modifiche nella proprieta Data, occorre chiamare il 
metodo MergeChangeLog. II paragrafo "Fusione delle modifiche nei dati" a 
pagina 27-36 descrive questa procedura. 

E impossibile utilizzare MergeChangeLog se si utilizza il dataset client per 
memorizzare in cache gli aggiornamenti o per rappresentare i dati da un componente 
provider esterno. Le informazioni nel registro delle modifiche sono necessarie per la 
risoluzione dei record aggiornati con i dati memorizzati nel database (o nel dataset 
sorgente). In alternativa, si puo chiamare ApplyUpdates, che tenta di scrivere le 
modifiche nel database server (o nel dataset sorgente) e aggiorna la proprieta Data 
solo quando le modifiche sono state inoltrate con successo. Per ulteriori informazioni 
su questa procedura, consultare "Applicazione degli aggiornamenti" a pagina 27-22. 

Definizione dei vincoli dei valori dati 



I dataset client possono imporre dei vincoli alle modifiche apportabili da un utente ai 
dati. Questi vincoli vengono applicati non appena l'utente tenta di registrare le 
modifiche nel registro delle modifiche. E sempre possibile fornire vincoli 
personalizzati. In questo modo e possibile preparare dei propri vincoli, definiti 
dall'applicazione, sui valori che gli utenti possono inviare a un dataset client. 

Inoltre, quando i dataset client rappresentano dati di un server a cui si accede 
mediante BDE, essi impongono anche i vincoli sui dati importati dal server di 
database. Se il dataset client opera con un componente provider esterno, il provider 
puo controllare se quei vincoli vengono inviati al dataset client e il dataset client puo 
controllare se li utilizza. Per ulteriori informazioni su come il provider controlla se i 
vincoli sono inclusi nei pacchetti dati, consultare "Gestione dei vincoli del server" a 
pagina 28-13. Per i dettagli su come e perche il dataset client puo disattivare 
l'imposizione dei vincoli del server, consultare "Gestione dei vincoli dal server" a 
pagina 27-32. 
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Specifica di vincoli custom 

E possibile utilizzare le proprieta dei componenti campo del dataset client per 
imporre dei vincoli sui dati che l'utente pud immettere. Ogni componente campo ha 
due proprieta che e possibile utilizzare per specificare i vincoli: 

• La proprieta DefaultExpression definisce un valore predefinito che viene assegnato 
al campo nel caso in cui l'utente non immetta un valore. Si noti che se anche il 
database server, o il dataset sorgente, assegna al campo un'espressione 
predefinita, la versione del dataset client ha la precedenza perche viene assegnata 
prima che l'aggiornamento sia applicato al database server o al dataset sorgente. 

• La proprieta Custom-Constraint consente di assegnare una condizione restrittiva che 
deve essere soddisfatta prima di poter confermare il valore del campo. I vincoli 
custom definiti in questo modo vengono imposti in aggiunta a tutte le restrizioni 
importate dal server. Per ulteriori informazioni sulle operazioni con i vincoli 
custom sui componenti campo, consultare "Creazione di un vincolo custom" a 
pagina 23-22. 

In aggiunta, tramite la proprieta Constraints del dataset client, e possibile creare 
anche vincoli a livello di record. Constraints e una raccolta di oggetti 
TCheckConstraint, in cui ciascun oggetto rappresenta una condizione differente. 
Utilizzare la proprieta Custom-Constraint di un oggetto TCheckConstraint per 
aggiungere i propri vincoli che saranno controllati al momento della registrazione 
dei record. 

Ordinamento e indicizzazione 



L'uso degli indici fornisce diversi vantaggi alle applicazioni: 

• Consente ai dataset client di individuare rapidamente i dati. 

• Permettono di applicare gli intervalli per limitare i record disponibili. 

• Permettono alle applicazioni di impostare relazioni con altri dataset come tabelle 
di consultazione o schede master/ detail. 

• Consente di specificare l'ordine in cui devono apparire i record. 

Se un dataset client rappresenta i dati di un server o utilizza un provider esterno, 
eredita un indice e un criterio di ordinamento predefinito in base ai dati che riceve. 
L'indice predefinito si chiama DEFAULT_ORDER. Si pud utilizzare questo 
ordinamento, ma non e possibile cambiare o cancellare l'indice. 

Oltre all'indice predefinito, il dataset client mantiene un secondo indice, denominato 
CHANGEINDEX, sui record modificati nel registro delle modifiche (proprieta Delta). 
CHANGEINDEX ordina tutti i record del dataset client come apparirebbero se 
venissero applicate le modifiche specificate in Delta. CHANGEINDEX si basa 
sull'ordinamento ereditato da DEFAULT_ORDER. Come avviene con 
DEFAULT_ORDER, non e possibile cambiare o cancellare l'indice CHANGEINDEX. 

E possibile utilizzare altri indici esistenti o crearne di propri. Nelle sezioni seguenti 
viene descritta la procedura per la creazione e l'uso degli indici con i dataset client. 
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Potrebbe essere opportuno riesaminare gli argomenti relativi agli indici nei dataset di 
tipo tabella, validi anche nel caso dei dataset client. Gli argomenti sono trattati nelle 
sezioni "Ordinamento dei record con indici" a pagina 22-27 e "Limitazione dei 
record con gli intervalli" a pagina 22-32. 

Aggiunta di un nuovo indice 

Esistono due modi per aggiungere indici ad un dataset client: 

• Per creare in fase di esecuzione un indice temporaneo che ordini i record del 
dataset client e possibile utilizzare la proprieta IndexFieldNames. Indicare i nomi 
dei campi, separandoli con il carattere punto e virgola. La sequenza con cui sono 
indicati i campi nell'elenco determina il loro ordine nell'indice. 

Questo e il metodo meno efficiente per aggiungere indici. Non e possibile 
specificare indici discendenti, o che tengano conto di maiuscole e minuscole, e 
l'indice risultante non supporta il raggruppamento. Una volta chiuso il dataset, 
questi indici non sono permanenti e non vengono salvati se si salva il dataset client 
in un file. 

• Per creare in fase di esecuzione un indice utilizzabile per il raggruppamento, 
chiamare il metodo Addlndex. Addlndex consente di specificare le proprieta 
dell'indice, compresi: 

• II nome dell'indice. Questo puo essere utilizzato per cambiare gli indici in fase 
di esecuzione. 

• I campi che costituiscono l'indice. L'indice utilizza tali campi per ordinare i 
record e per individuare i record che hanno valori specifici in quei campi. 

• La modalita secondo la quale l'indice ordina i record. Per impostazione definita, 
gli indici impongono un ordinamento crescente (basato sulla macchina locale). 
Questo ordinamento predefinito tiene conto della differenza tra lettere 
maiuscole e minuscole. E possibile specificare delle opzioni che facciano si che 
l'intero indice ignori la differenza tra maiuscole e minuscole o che ordinino in 
modo discendente. In alternativa, e possibile fornire una lista di campi da 
ordinare senza tener conto delle maiuscole \ minuscole e una lista di campi da 
ordinare in ordine discendendente. 

• II livello predefinito di raggruppamento supportato per l'indice. 

Gli indici creati con Addlndex non permangono quando si chiude il dataset client. 
(Ovvero, vanno persi quando si riapre il dataset client). Non e possibile chiamare 
Addlndex quando il dataset e chiuso. Gli indici che vengono aggiunti tramite 
Addlndex non vengono salvati quando si salva il dataset client in un file. 

• II terzo modo per creare un indice consiste nel crearlo al momento della creazione 
del dataset client. Prima di creare il dataset client, specificare gli indici desiderati 
utilizzando la proprieta IndexDefs. Gli indici vengono creati in un secondo 
momento insieme al dataset associato quando si chiamera CreateDataSet. Per 
ulteriori informazioni sulla creazione di dataset client, consultare "Creazione e 
cancellazione di tabelle" a pagina 22-40. 
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Come con Addlndex, gli indici creati con il raggruppamento del supporto del 
dataset possono eseguire l'ordinamento ascendente su alcuni campi e discendente 
su altri, e possono tenere conto delle maiuscole / minuscole su alcuni campi e non 
su altri. Gli indici cosi creati permangono sempre e vengono salvati quando si 
salva il dataset client in un file. 

L'indicizzazione e l'ordinamento possono essere effettuati sono sui campi calcolati 
« internamente con i dataset client. 



Cancellazione e cambio degli indici 

Per rimuovere un indice creato per un dataset client, occorre chiamare Deletelndex e 
specificare il nome dell'indice da rimuovere. Non e possibile cancellare gli indici 
DEFAULT_ORDER e CHANGEINDEX. 

Per usare un indice diverso quando sono disponibili piu indici, si deve ricorrere alia 
proprieta IndexName per selezionare l'indice da utilizzare. In progettazione, si puo 
operare la scelta dagli indici disponibili nella casella a discesa della proprieta 
IndexName dell'Object Inspector. 

Uso degli indici per il raggruppamento dei dati 

Quando si usa un indice nel dataset client, questo impone automaticamente un tipo 
di ordinamento sui record. Dato questo ordinamento, i record adiacenti 
generalmente contengono valori duplicati nei campi che costituiscono l'indice. Per 
esempio, si consideri il seguente frammento di una tabella ordini indicizzata sui 
campi SalesRep e Customer: 



SalesRep 


Customer 


OrderNo 


Amount 


l 


l 


5 


100 


l 


l 


2 


50 


l 


2 


3 


200 


l 


2 


6 


75 


2 


1 


1 


10 


2 


3 


4 


200 



Dato questo ordinamento, i valori adiacenti nella colonna SalesRep sono duplicati. Lo 
stesso avviene all'interno dei record di SalesRep 1, i cui valori adiacenti della colonna 
Customer sono duplicati.Cioe, i dati sono raggruppati per SalesRep e all'interno del 
gruppo SalesRep sono raggruppati per Customer. Ogni raggruppamento ha un 
livello associato. In questo caso il gruppo SalesRep ha il livello 1 (in quanto non e 
annidato in nessun altro gruppo), mentre il gruppo Customer ha come livello 2 (in 
quanto e annidato nel gruppo con il livello 1). II livello di raggruppamento 
corrisponde all'ordine dei campi nell'indice. 

I dataset client consentono di determinare dove sta il record attivo all'interno di un 
determinate livello di raggruppamento. Cio consente all'applicazione di visualizzare 
i record in modo differente, a seconda che si tratti del primo record del gruppo, della 
parte centrale di un gruppo o dell'ultimo record di un gruppo. Per esempio, si 
potrebbe voler visualizzare il valore di un campo solo se e il primo record del 
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gruppo, eliminando i valori duplicati. Questa operazione con la tabella precedente 
produce il seguente risultato: 



SalesRep Customer OrderNo Amount 

1 1 5 100 

2 50 

2 3 200 
6 75 

2 1 1 10 

3 4 200 



Per determinare dove cade il record attivo all'interno di un gruppo, si deve ricorrere 
al metodo GetGroupState. GetGroupState accetta un integer corrispondente al livello 
del gruppo e restituisce un valore che indica dove cade il valore corrente nel gruppo 
(primo record, secondo record o nessuno dei due). 

Quando si crea un indice, si pud specificare il livello di raggruppamento supportato 
(fino al numero dei campi dell'indice). GetGroupState non e in grado di fornire 
informazioni sui gruppi oltre quel livello, anche se l'indice ordina i record 
utilizzando campi aggiuntivi. 

Rappresentazione dei valori calcolati 



Come con qualunque dataset, e possibile aggiungere campi calcolati al dataset client. 
Questi sono campi i cui valori vengono calcolati in modo dinamico, generalmente 
sulla base dei valori di altri campi dello stesso record. Per ulteriori informazioni 
sull'uso dei campi calcolati, consultare "Definizione di un campo calcolato" a 
pagina 23-7. 

I dataset client, tuttavia, consentono l'ottimizzazione quando i campi vengono 
calcolati utilizzando i campi calcolati internamente. Per maggiori informazioni sui 
campi calcolati internamente, consultare il paragrafo successivo "Uso di campi 
calcolati internamente nei dataset client". 

E anche possibile comunicare ai dataset client di creare campi calcolati che sommino i 
dati di diversi record utilizzando le aggregazioni di manutenzione. Per ulteriori 
informazioni sulla aggregazioni di manutenzione, consultare "Uso delle 
aggregazioni di manutenzione" a pagina 27-12. 

Uso di campi calcolati internamente nei dataset client 

Negli altri dataset l'applicazione deve calcolare il valore dei campi calcolati ogni 
volta che cambia il record o l'utente modifica dei campi del record attivo. Cio awiene 
in un gestore di even to OnCalcFields. 

Anche se e ancora possibile procedere in questo modo, i dataset client consentono di 
ridurre al minimo il numero di volte in cui i campi calcolati devono essere ricalcolati, 
salvandoli nei dati del dataset client. Quando i valori calcolati vengono salvati con il 
dataset client, essi devono ancora essere ricalcolati quando l'utente modifica il record 
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attivo, ma l'applicazione non richiede il ricalcolo dei valori ogni volta che cambia il 
record attivo. Per salvare i valori calcolati nei dati del dataset client, si devono 
utilizzare i campi calcolati ulteriormente al posto dei campi calcolati. 

I campi calcolati internamente, esattamente come i campi calcolati, vengono elaborati 
in un gestore di even to OnCalcFields. Tuttavia, e possibile ottimizzare il gestore di 
evento contrassegnando la proprieta State del dataset client. Quando State e 
dsInternalCalc, occorre ricalcolare i campi calcolati internamente. Quando State e 
dsCalcFields, occorre ricalcolare i campi calcolati normali. 

Per usare i campi calcolati internamente, occorre definire i campi come tali prima di 
creare il dataset client. A seconda che si utilizzino i campi persistenti o le definizioni 
di campo, l'operazione viene svolta in uno dei seguenti modi: 

• Se si utilizzano campi persistenti, si devono definire i campi come calcolati 
internamente selezionando InternalCalc nel Fields editor. 

• Se si utilizzano le definizioni dei campi, impostare a true la proprieta 
InternalCalcField della definizione rilevante del campo. 

Altri tipi di dataset utilizzano campi calcolati internamente. Tuttavia, con gli altri 
dataset questi valori non vengono calcolati in un gestore di evento OnCalcFields. 
Invece, vengono calcolati automaticamente tramite da BDE o da un server di 
database remoto. 

Uso delle aggregazioni di manutenzione 



I dataset client forniscono il supporto per il riepilogo dei dati provenienti da gruppi 
di record. Dal momento che questi riepiloghi vengono aggiornati automaticamente 
quando si modificano i dati del dataset, questi dati riepilogati vengono definiti una 
"aggregazione di manutenzione." 

Nella loro forma piu semplice le aggregazioni di manutenzione consentono di 
ottenere informazioni come la somma di tutti i valori di una colonna del dataset 
client. Esse sono, comunque, sufficientemente flessibili per supportare un grande 
numero di calcoli di somma e di fornire totali parziali di gruppi di record definiti in 
un indice che supporta il raggruppamento. 

Specifica delle aggregazioni 

Per specificare che si vogliono calcolare riepiloghi di record di un dataset client, si 
deve ricorrere alia proprieta Aggregates. Aggregates e una raccolta di specif i che di 
aggregazione (TAggregate). E possibile aggiungere tali specifiche al dataset client 
utilizzando il Collection Editor in progettazione o il metodo Add di Aggregates in 
esecuzione. Se si vogliono creare componenti campo per le aggregazioni, occorre 
creare campi persistenti per i valori di aggregazione nel Fields Editor. 

Quando si creano campi di aggregazione, alia proprieta Aggregates del dataset client 
vengono aggiunti automaticamente gli oggetti appropriati di aggregazione. Non 
occorre aggiungerli in modo esplicito durante la creazione dei campi persistenti di 
aggregazione. Per ulteriori dettagli sulla creazione dei campi persistenti di 
aggregazione, consultare "Definizione di un campo di aggregazione" a pagina 23-10. 
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Per ciascuna aggregazione la proprieta Expression indica il calcolo di riepilogo che 
rappresenta. Expression pud contenere una semplice espressione di riepilogo come 

Suin(Fieldl) 

oppure un'espressione complessa che abbina informazioni di campi diversi, come 

Sum(Qty * Price) - Sum(MountPaid) 

Le espressioni di aggregazione includono uno o piu degli operatori di riepilogo 
riportati nella Tabella 27.2 

Tabella 27.2 Operatori di riepilogo per le aggregazioni di manutenzione 
Operatore Uso 

Sum Calcola il totale dei valori di un campo numerico o di un'espressione 

Avg Calcola il valore mezzo di un campo numerico o data-ora oppure di un'espressione 

Count Specifica il numero di valori non vuoti per un campo o un'espressione 

Min Indica il valore minimo per un campo stringa, numerico o data-ora oppure per 

un'espressione 

Max Indica il valore massimo per un campo stringa, numerico o data-ora oppure per 

un'espressione 

Gli operatori di riepilogo agiscono sui valori dei campi o sulle espressioni costruite 
dai valori dei campi utilizzando gli stessi operatori usati per creare i filtri.(In ogni 
caso non si possono annidare operatori di riepilogo). E possibile creare espressioni 
utilizzando operatori su valori di riepilogo con altri valori di riepilogo, o su valori di 
riepilogo e costanti. Tuttavia, non e consentito combinare valori di riepilogo e valori 
di campo, in quanto tali espressioni sono ambigue (non ci sono indicazioni su quale 
record deve fornire il valore del campo). Queste regole vengono illustrate nelle 
espressioni seguenti: 



Sum(Qty * Price) 
Max(Fieldl) - Max(Field2) 
Avg(DiscountRate) * 100 
Min(Suin(Fieldl) ) 
Count (Fieldl) - Field2 



{consentito - riepilogo di un'espressione su campi } 
{consentito - espressione su riepiloghi } 
{consentito - espressione di riepilogo e costante } 
{non consentito - riepiloghi annidati } 
{non consentito -- espressione di riepilogo e campo 



Aggregazione di gruppi di record 

Per impostazione predefinita, le aggregazioni di manutenzione vengono calcolate in 
modo che effettuino il riepilogo di tutti i record nel dataset client. Tuttavia, si pud 
anche specificare che si vuole effettuare il riepilogo sui record di un gruppo. Cio 
consente di fornire riepiloghi intermedi, come dei totali parziali per gruppi di record 
che condividono un valore di campo comune. 

Prima che sia possibile specificare un' aggregazione di manutenzione su un gruppo 
di record, bisogna ricorrere a un indice che supporti il raggruppamento appropriato. 
Per informazioni sui supporto per il raggruppamento, consultare "Uso degli indici 
per il raggruppamento dei dati" a pagina 27-10. 
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Una volta che si e in possesso di un indice che raggruppa in dati nel modo che si 
vuole che vengano riepilogati, occorre specificare le proprieta IndexName e 
GroupingLevel dell'aggregazione per indicare quale indice utilizza e quale gruppo o 
sottogruppo di quel indice definisce i record da riepilogare. 

Per esempio, si consideri il frammento seguente di una tabella ordini che e 
raggruppare per SalesRep e, all'interno di SalesRep, per Customer: 




1 1 5 100 

1 1 2 50 

1 2 3 200 

1 2 6 75 

2 1 1 10 
2 3 4 200 



II codice seguente imposta un'aggregazione di manutenzione che indica la quantita 
complessiva per ogni rivenditore: 

Agg->Expression = " Sum (Amount )" ; 
Agg->IndexName = "SalesCust" ; 
Agg->GroupingLevel = 1; 
Agg->AggregateName = "Total for Rep"; 

Per aggiungere un'aggregazione che effettui il riepilogo per ogni cliente all'interno di 
un determinate rivenditore, occorre creare un'aggregazione di manutenzione con 
livello2. 

Le aggregazioni di manutenzione che effettuano il riepilogo su un gruppo di record 
vengono associate con un indice specifico. La proprieta Aggregates puo includere 
aggregazioni che utilizzano indici diversi. Tuttavia, solo le aggregazioni che 
effettuano il riepilogo sull'intero dataset e quelle che utilizzano l'indice corrente sono 
valide. II cambiamento dell'indice corrente cambia le aggregazioni valide. Per 
determinare quali aggregazioni sono valide in qualunque momento, bisogna 
ricorrere alia proprieta ActiveAggs. 

Ottenimento dei valori di aggregazione 

Per ottenere il valore di un'aggregazione di manutenzione, occorre chiamare il 
metodo Value dell'oggetto T Aggregate che rappresenta l'aggregazione. Value 
restituisce l'aggregazione di manutenzione del gruppo che contiene il record corrente 
del dataset client. 

Quando si effettua il riepilogo dell'intero dataset client, si puo chiamare in 
qualunque momento Value per ottenere l'aggregazione di manutenzione. Tuttavia, 
quando si effettua il riepilogo su informazioni raggruppate, occorre verificare che il 
record attivo si trovi nel gruppo che si intende riepilogare. Pertanto, e consigliabile 
ottenere valori di aggregazione in tempi chiaramente specificati, come quando si 
passa sul primo record di un gruppo o ci si sposta sull'ultimo. Per determinare dove 
cade il record attivo all'interno di un gruppo, si deve utilizzare il metodo 
GetGroupState. 
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Per visualizzare le aggregazioni di manutenzione nei controlli associati ai dati, si 
deve utilizzare il Fields editor per creare un componente campo persistente di 
aggregazione. Quando si specifica un campo di aggregazione nel Fields editor, 
Aggregates del dataset client viene aggiornato automaticamente, in modo da 
includere la specifica di aggregazione appropriata. La proprieta AggFields contiene il 
nuovo componente campo di aggregazione, che viene restituito dal metodo FindField. 



Copia di dati da un altro dataset 



Per copiare in progettazione i dati da un altro dataset, fare clic con il pulsante destro 
sul dataset e scegliere Assign Local Data. Apparira una finestra di dialogo con 
l'elenco di tutti i dataset disponibili nel progetto. Selezionare quello di cui si vogliono 
copiare dati e struttura e scegliere OK. Quando si copia il dataset sorgente, viene 
attivato automaticamente il dataset client. 

Per copiare dati da un altro dataset in fase di esecuzione, e possibile assegnare 
direttamente i dati, oppure, se il sorgente e un altro dataset client, clonare il cursor. 

Assegnazione diretta dei dati 

La proprieta Data del dataset client puo essere utilizzato per assegnare a un dataset 
client i dati di un altro dataset. Data e un pacchetto dati sotto forma di OleVariant. Un 
pacchetto dati puo derivare da un altro dataset client, o da qualunque altro dataset 
utilizzando un provider. Una volta che un pacchetto dati e stato assegnato a Data, il 
suo contenuto viene visualizzato automaticamente nei controlli associati ai dati 
connessi al dataset client tramite un componente datasource. 

Quando si apre un dataset client che rappresenta i dati di un server o che utilizza un 
componente provider esterno, i pacchetti dati vengono assegnati automaticamente a 
Data. 

Quando il dataset client non usa un provider, e possibile copiare i dati da un altro 
dataset nel modo seguente: 

ClientDataSetl->Data = ClientDataSet2->Data; 

Quando si copia la proprieta Data di un altro dataset client, si copia anche il registro 
delle modifiche, ma la copia non riflette i filtri o gli intervalli che sono stati applicati. 
Per includere i filtri o gli intervalli, occorre clonare il cursor del dataset sorgente. 

Se si effettua la copia da un dataset alternative rispetto ad un dataset client, si puo 
creare un componente provider del dataset, collegarlo al dataset sorgente e poi 
copiarne i dati: 

TempProvider = new TDataSetProvider(Forml) ; 
TempProvider->DataSet = SourceDataSet; 
ClientDataSetl->Data = TempProvider->Data; 
delete TempProvider; 

Quando si assegnano direttamente i dati alia proprieta Data, il nuovo pacchetto dati 
viene fuso nei dati esistenti. Tutti i dati precedenti vengono, invece, sostituiti. 

Se si intendono fondere le modifiche ricavandole da un altro dataset, anziche 
copiarne i dati, si deve utilizzare un componente provider. Creare un provider di 
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dataset come nell'esempio precedente, ma associarlo al dataset di destinazione e, 
anziche copiare la proprieta Data, utilizzare il metodo ApplyUpdates: 

TempProvider = new TDataSetProvider(Forml) ; 
TempProvider->DataSet = ClientDataSetl; 

TempProvider->ApplyUpdates (SourceDataSet->Delta, -1, ErrCount) ; 
delete TempProvider; 

Clonazione di un cursor di un dataset client 

I dataset client utilizzano il metodo CloneCursor per permettere di gestire in fase di 
esecuzione una seconda vista dei dati. CloneCursor consente a un secondo dataset 
client di condividere i dati del dataset client originale. Cio e meno oneroso della copia 
di tutti i dati originali, ma, dal momento che i dati sono condivisi, il secondo dataset 
client non puo modificare i dati senza influenzare il dataset client originale. 

CloneCursor richiede tre parametri: Source specifica il dataset client da clonare. Gli 
ultimi due parametri (Reset e KeepSettings) indicano se copiare informazioni diverse 
dai dati. Queste informazioni comprendono tutti i filtri, l'indice attivo, i collegamenti 
a una tabella master (quando il dataset sorgente e un set di dettaglio), la proprieta 
ReadOnly e tutti i collegamenti a un componente connessione o a un interfaccia 
provider. 

Quando Reset e KeepSettings sono false, viene aperto un dataset client clonato e 
vengono utilizzate le impostazioni del dataset sorgente per definire le proprieta della 
destinazione. Quando Reset e true, alle proprieta del dataset di destinazione vengono 
attribuiti i valori predefiniti (non viene specificato nessun indice o filtro, nessuna 
tabella master, nessun componente connessione o provider, e ReadOnly e false). 
Quando KeepSettings e true, le proprieta del dataset di destinazione non vengono 
modificate. 

Aggiunta di informazioni specifiche per I'applicazione ai dati 



Gli sviluppatori di applicazioni possono aggiungere informazioni personalizzate alia 
proprieta Data del dataset client. Dal momento che queste informazioni vengono 
fornite insieme al pacchetto dati, esse vengono incluse quando si salvano i dati in un 
file o in un flusso. Esse vengono copiate quando si copia i dati in un altro dataset. 
Opzionalmente, possono essere incluse con la proprieta Delta in modo che un 
provider possa leggerle quando riceve gli aggiornamenti dai dataset client. 

Per salvare con la proprieta Data informazioni specifiche per I'applicazione, si deve 
usare il metodo SetOptionalParam. Questo consente di memorizzare un Ole Variant 
che contiene i dati con un nome specifico. 

Per recuperare queste informazioni specifiche dell'applicazione, si deve ricorrere al 
metodo GetOptionalParam, passando il nome utilizzato quando sono state 
memorizzate le informazioni. 
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Utilizzo di un dataset client per registrare in cache gli 
aggiornamenti 

Per impostazione predefinita, quando si modif icano i dati nella maggior parte dei 
dataset, ogni volta che si cancella o si registra un record, il dataset genera una 
transazione, cancella o scrive quel record nel server di database e convalida la 
transazione. Se nello scrivere le modifiche nel database si verifica un problema, 
l'applicazione viene immediatamente informata: il dataset solleva un'eccezione 
quando si registra il record. 

Se il dataset utilizza un server di database remoto, questo approccio puo degradare le 
prestazioni a causa del traffico di rete tra l'applicazione e il server ogni volta che ci si 
sposta a un nuovo record dopo avere modificato il record corrente. Per minimizzare 
il traffico di rete, potrebbe essere opportuno memorizzare gli aggiornamenti nella 
cache locale. Quando si memorizzano gli aggiornamenti nella cache, l'applicazione 
preleva i dati dal database, li memorizza nella cache e lo modifica in locale e quindi 
applica gli aggiornamenti in cache al database con una singola transazione. Se si 
utilizzano gli aggiornamenti in cache, le modifiche a un dataset (come la 
registrazione delle modifiche o la cancellazione di record) vengono memorizzate in 
locale invece di essere scritte direttamente nella tabella associata al dataset. Una volta 
completate le modifiche, l'applicazione chiama un metodo che scrive nel database le 
modifiche memorizzate nella cache e azzera la cache. 

Gli aggiornamenti in cache possono ridurre al minimo la durata della transazione e 
limitare il traffico nella rete.Tuttavia, i dati nella cache sono locali rispetto 
all'applicazione e non sono sotto il controllo della transazione. Tuttavia, i dati nella 
cache sono locali all'applicazione e non sono sotto il controllo della transazione. Cio 
significa che mentre si lavora sulla propria copia locale in memoria dei dati, altre 
applicazioni potrebbero modificare i dati nella tabella di database sottostante. Inoltre, 
non sono in grado di vedere alcuna modifica finche gli aggiornamenti memorizzati 
in cache non saranno applicati. Per questo motivo, l'uso degli aggiornamenti in cache 
potrebbe non essere appropriate per applicazioni che operano con dati volatili, dal 
momento che si potrebbero causare o incontrare troppi conflitti non appena si 
cerchera di fondere le modifiche nel database. 

Benche BDE e ADO forniscano meccanismi alternativi per la memorizzazione in 
cache degli aggiornamenti, l'utilizzo di un dataset client a tale scopo presenta diversi 
vantaggi: 

• L'applicazione degli aggiornamenti quando i dataset sono collegati mediante 
relazioni master/ detail e gestita automaticamente. Questo fatto garantisce che gli 
aggiornamenti a piu dataset collegati vengano applicati nell'ordine corretto. 

• I dataset client offrono il massimo controllo sul processo di aggiornamento. E 
possibile impostare delle proprieta per influire sulle istruzioni SQL generate per 
l'aggiornamento di record, per specificare la tabella da utilizzare durante 
l'aggiornameto di record provenienti da una join su piu tabelle, o addirittura 
applicare gli aggiornamenti manualmente mediante da un gestore di evento 
BeforeUpdateRecord. 
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• Se durante l'applicazione al server di database degli aggiornamenti in cache si 
verificano degli errori, solo i dataset client (e i provider di dataset) sono in grado 
di fornire informazioni sul valore attuale del record nel server di database, oltre al 
valore originale (non modificato) presente nel dataset e al nuovo valore 
(modificato) deH'aggiomamento che non e andato a buon fine. 

• I dataset client permettono di specificare il numero di errori di aggiornamento che 
si desidera tollerare prima che l'intero aggiornamento venga annullato. 

Panoramica sull'utilizzo degli aggiornamenti in cache 



Per utilizzare gli aggiornamenti in cache, le varie fasi elaborative devono avvenire in 
un'applicazione secondo l'ordine seguente: 

1 Indicare i dati che si vogliono modificare. La modalita operativa dipende dal tipo 
di dataset client utilizzato: 

• Se si utilizza TCHentDataSet, specificare il componente provider che rappresenta 
i dati che si vogliono modificare. L'operazione e descritta in "Specifica di un 
provider" a pagina 27-27. 

• Se si utilizza un dataset client associato a un particolare meccanismo di accesso 
di dati, e necessario 

- Identificare il server di database impostando la proprieta DBConnection a un 
componente connection appropriate 

- Indicare quali dati si vogliono vedere specificando le proprieta 
CommandTexte CommandType. La proprieta CommandType indica se 
CommandText rappresenta un'istruzione SQL da eseguire, il nome di una 
procedura registrata oppure il nome di una tabella. Se CommandText e una 
query o una procedura registrata, utilizzare la proprieta Params per fornire 
tutti i parametri di input. 

- Facoltativamente, utilizzare la proprieta Options per indicare se i set di 
dettaglio annidati e i dati BLOB devono essere inclusi nei pacchetti dati o 
recuperati separatamente, se determinati tipi di modifiche (inserimenti, 
modifiche o cancellazioni) devono essere disattivati, se un singolo 
aggiornamento puo influire su piu record del server e se i record del dataset 
client devono essere aggiornati all'atto dell'applicazione degli 
aggiornamenti. La proprieta Options e identica alia proprieta Options del 
provider. Pertanto, essa permette di impostare anche opzioni che non sono 
pertinenti o appropriate. Ad esempio, non e'e alcun motivo di includere 
poIncFieldProps, in quanto il dataset client non recuperara i propri dati da un 
dataset con campi persistenti. Per contro, non si vorra escludere 
poAllowCommandText, incluso per default, perche cio disattiverebbe la 
proprieta CommandText utilizzata da dataset client per specificare i dati da 
ottenere. Per informazioni sulla proprieta Options del provider, consultare il 
paragrafo "Impostazione di opzioni che influenzano i pacchetti dati" a 
pagina 28-5. 

2 Visualizzare e modificare i dati, permettere l'inserimento di nuovi record e 
supportare la cancellazione di record esistenti. Sia la copia originale di ogni record 
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che tutte le modifiche vengono conservate in memoria. Questo procedimento e 
descritto in "Editing di dati" a pagina 27-5. 

3 Prelevare altri record in base alle necessita. Per impostazione predefinita, i 
dataset client prelevano tutti i record e li conservano in memoria. Se un dataset 
contiene molti record o record con grandi campi BLOB, potrebbe essere opportuno 
modificare questo comportamento in modo che il dataset client prelevi solo la 
quantita necessaria di record da visualizzare e ne prelevi successivamente altri se 
necessario. Per i dettagli su come controllare il processo di prelievo dei record, 
vedere "Richiesta di dati da un dataset sorgente o da un documento" a 

pagina 27-28. 

4 A propria scelta, aggiornare i record. Man mano che il tempo trascorre, altri utenti 
potrebbero modificare i dati sul server di database. Cio fa si che i dati del dataset 
client siano sempre piu differenti dai dati sul server, accrescendo la possibilita che 
si verifichino errori al momento dell'applicazione degli aggiornamenti. Per 
attenuare questo problema, e possibile aggiornare i record che non sono stati 
ancora modificati. Per i dettagli, vedere "Rinnovo dei record" a pagina 27-33. 

5 Applicare i record nella cache locale al database o annullare gli aggiornamenti. 

Per ogni record scritto nel database, viene innescato un evento BeforeUpdateRecord. 
Se si verifica un errore nel momento in cui viene scritto nel database un singolo 
record, un evento OnllpdateError permette all'applicazione di correggere l'errore, 
se possibile, e di continuare l'aggiornamento. Una volta completati gli 
aggiornamenti, tutti gli aggiornamenti applicati con successo vengono rimossi 
dalla cache locale. Per ulteriori informazioni sull'applicazione degli aggiornamenti 
al database, vedere "Aggiornamento dei record" a pagina 27-21. 

Invece di applicare aggiornamenti, un'applicazione puo annullare gli 
aggiornamenti, svuotando il registro delle modifiche senza scrivere le modifiche 
nel database. E possibile annullare gli aggiornamenti chiamando il metodo 
CancelUpdates. Tutti i record cancellati presenti nella cache vengono ripristinati, i 
record modificati assumono i valori originali e i record appena inseriti spariscono. 

Scelta del tipo di dataset per gli aggiornamenti in cache 



C++Builder include alcuni componenti dataset client specializzati per gli 
aggiornamenti in cache. Ogni dataset client e associato a un particolare meccanismo 
di accesso di dati. Essi vengono elencati nella Tabella Tabella 27.3: 

Tabella 27.3 Dataset client specializzati per gli aggiornamenti in cache 





Meccanismo di accesso ai 


Dataset client 


dati 


TBDEClientDataSet 


Borland Database Engine 


TSQLClientDataSet 


dbExpress 


TIBClientDataSet 


InterBase Express 



Inoltre, e possibile memorizzare in cache gli aggiornamenti utilizzando il dataset 
client generico (TClientDataSet) con un provider e un dataset sorgente esterni. Per 
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informazioni sull'uso di TClientDataSet con un provider esterno, consultare "Uso di 
un dataset client con un provider di dati" a pagina 27-26. 

Anche i dataset client specializzati associati a un particolare meccanismo di accesso ai 
dati in effetti utilizzano un provider e un dataset sorgente. Tuttavia, sia il provider 
che il dataset sorgente sono interni al dataset client. 

E piu semplice utilizzare uno dei dataset client specializzati per gli aggiornamenti in 
cache. A volte, tuttavia, e preferibile utilizzare TClientDataSet con un provider 
esterno: 

• Se si utilizza un meccanismo di accesso di dati che non ha un dataset client 
specializzato, e necessario utilizzare TClientDataSet con un componente provider 
esterno. Ad esempio, se i dati provengono da un documento XML o da un dataset 
custom. 

• Se si opera con tabelle collegate mediante una relazione master/ detail, si dovrebbe 
utilizzare TClientDataSet e connetterlo, utilizzando un provider, alia tabella master 
dei due dataset sorgente collegati con una relazione master/ detail. II dataset client 
vede il dataset di dettaglio come un campo di dataset annidato. Questa modalita 
operativa e necessaria per poter applicare gli aggiornamenti alle tabelle master e 
detail nell'ordine corretto. 

• Se si vogliono creare gestori di evento che rispondono alia comunicazione fra il 
dataset client e il provider (ad esempio, prima e dopo che il dataset client ha 
prelevato i record dal provider), e necessario utilizzare TClientDataSet con un 
componente provider esterno. I dataset client specializzati pubblicano gli eventi 
piu importanti per l'applicazione degli aggiornamenti (OnReconcileError, 
BeforeUpdateRecord e OnGetTableName), ma non pubblicano gli eventi inerenti alia 
comunicazione fra il dataset client e il suo provider, in quanto sono destinati 
principalmente alle applicazioni multi-tier. 

• Se si utilizza BDE, potrebbe essere opportuno utilizzare un provider e un dataset 
sorgente esterni perche potrebbe essere necessario utilizzare un oggetto update. 
Benche sia possibile codificare un oggetto update a partire dal gestore di evento 
BeforeUpdateRecord di TBDEClientDataSet, e molto piu semplice assegnare 
semplicemente la proprieta UpdateObject del dataset sorgente. Per informazioni 
sull'utilizzo di oggetti update, vedere "Aggiornamento di dataset mediante 
oggetti update" a pagina 24-41. 

Indicazione dei record modificati 



Mentre l'utente modifica un dataset client, pud essere utile fornire un riscontro sulle 
modiche apportate. In particolar modo e utile nel caso si voglia permettere all'utente 
di annullare determinate modifiche, ad esempio, spostandosi sulla modifica e 
facendo clic su un pulsante "Annulla. 

II metodo UpdateStatus e le proprieta StatusFilter sono utili quando si vuole fornire un 
riscontro degli aggiornamenti effettuati: 

• UpdateStatus indica il tipo di aggiornamento, se vi e stato, che e stato apportato al 
record corrente. Puo assumere uno dei seguenti valori: 
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• usllnmodified indica che il record corrente e invariato. 

• usModified. indica che il record corrente e stato modificato. 

• uslnserted indica un record che e stato inserito dall'utente. 

• usDeleted indica un record che e stato cancellato dall'utente. 

• StatusFilter controlla quali tipi di aggiornamento sono visibili nel registro delle 
modifiche. StatusFilter opera sui record nella cache in modo simile a quanto fanno 
i filtri sui normali dati. StatusFilter e un set, e pertanto puo contenere una qualsiasi 
combinazione dei seguenti valori: 

• usllnmodified indica un record invariato. 

• usModified indica un record modificato. 

• uslnserted indica un record inserito. 

• usDeleted indica un record cancellato. 

Per impostazione predefinita, StatusFilter e il set [usModified, uslnserted, 
usllnmodified]. A questo set e possibile aggiungere usDeleted in modo da fornire un 
riscontro sui record cancellati. 

UpdateStatus e StatusFilter sono utili anche nei gestori di evento BeforellpdateRecord e 
OnReconcileError. Per informazioni su BeforellpdateRecord, vedere "Interventi durante 
l'applicazione degli aggiornamenti" a pagina 27-23. Per informazioni su 
OnReconcileError, consultare "Riconciliazione degli errori di aggiornamento" a 
pagina 27-25. 

II seguente esempio mostra come fornire un riscontro sullo stato di aggiornamento 
dei record utilizzando il metodo UpdateStatus. L'esempio parte dall'assunto che la 
proprieta StatusFilter sia stata modificata includendo usDeleted, permettendo cosi la 
visualizzazione nel dataset dei record cancellati. Inoltre presuppone che al dataset sia 
stato aggiunto un campo calcolato di nome "Status." 

void __fastcall TForml : :ClientDataSetlCalcFields (TDataSet *DataSet) 
{ 

switch (DataSet->UpdateStatus ( ) ) 
{ 

case usllnmodified: 

ClientDataSetlStatus->Value = NULL; break; 
case usModified: 

ClientDataSetlStatus->Value = "M"; break; 
case usLnserted: 

ClientDataSetlStatus->Value = "I"; break; 
case usDeleted: 

ClientDataSetlStatus->Value = "D"; break; 

} 

} 

Aggiornamento dei record 



II contenuto del registro delle modifiche viene memorizzato come pacchetto dati 
nella proprieta Delta del dataset client. Per rendere permanenti le modifiche in Delta, 
il dataset client deve applicarle al database (o al dataset sorgente o al documento 
XML). 
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Quando un client applica gli aggiornamenti al server, si verifica quanto segue: 

1 L'applicazione client chiama il metodo Applyllpdates di un oggetto dataset client. 
Questo metodo passa il contenuto della proprieta Delta del dataset client al 
provider (interno o esterno). Delta e un pacchetto dati che contiene i record 
aggiornati, inseriti e cancellati del dataset client. 

2 II provider applica gli aggiornamenti, memorizzando nella cache tutti i record con 
problemi che non e in grado di risolvere da solo. Per informazioni dettagliate su 
come il provider applica gli aggiornamenti, consultare la sezione "Risposta alle 
richieste di aggiornamento del client" a pagina 28-8. 

3 II provider restituisce tutti i record non risolti al client dataset in un pacchetto dati 
Result. II pacchetto dati Result contiene tutti i record che non sono stati aggiornati. 
Contiene inoltre informazioni sugli errori, come i messaggi e i codici di errore. 

4 L'applicazione client dataset tenta di riconciliare gli errori di aggiornamento 
restituiti nel pacchetto Result record per record. 

Applicazione degli aggiornamenti 

Le modifiche apportate alia copia locale di dati del dataset client non vengono inviate 
al server di database (o al documento XML) finche l'applicazione client non chiama il 
metodo Applyllpdates del dataset. Applyllpdates prende le modifiche nel registro delle 
modifiche e le invia come pacchetto dati (denominate Delta) al provider. (Si noti che, 
nella maggior parte dei dataset client, il provider e interno al dataset client.) 

Applyllpdates accetta un singolo parametro, MaxErrors, che indica il numero massimo 
di errori che il provider pud tollerare prima che venga interrotto l'intero processo di 
aggiornamento. Se MaxErrors e 0, non appena si verifica un errore di aggiornamento, 
viene terminato l'intero processo di aggiornamento. Nessuna modifica viene scritta 
nel database e il registro delle modifiche del dataset client rimane intatto. Se 
MaxErrors e -1, viene tollerato un numero qualunque di errori e il registro delle 
modifiche contiene tutti i record che non e stato possibile aggiornare. Se MaxErrors e 
un valore positivo e si verifica un numero di errori maggiore di quello consentito da 
MaxErrors, tutti gli aggiornamenti vengono abbandonati. Se si verifica un numero di 
errori minore di quello specificato da MaxErrors, tutti i record aggiornati vengono 
cancellati automaticamente dal registro delle modifiche del dataset client. 

Applyllpdates restituisce il numero di errori effettivi incontrati, che e sempre minore o 
uguale a MaxErrors piu uno. Questo valore di ritorno indica il numero di record che 
non possono essere scritti nel database. 

II metodo Applyllpdates del dataset client compie le seguenti operazioni: 

1 Chiama indirettamente il metodo Applyllpdates del provider .11 metodo 
Applyllpdates del provider scrive gli aggiornamenti nel database, nel dataset 
sorgente o nel documento XML e tenta di correggere tutti gli errori che incontra. I 
record che non e possibile aggiornare a causa di condizioni di errore vengono 
rinviati al dataset client. 

2 II metodo Applyllpdates del dataset client tenta quindi di riconciliare questi record 
con problemi chiamando il metodo Reconcile. Reconcile e una routine di gestione 
degli errori che chiama il gestore di evento OnReconcileError. Per correggere gli 
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errori e necessario scrivere il codice del gestore di evento OnReconcileError. Per 
informazioni su OnReconcileError, consultare "Riconciliazione degli errori di 
aggiornamento" a pagina 27-25. 

3 Infine, Reconcile rimuove dal registro le modifiche apportate con esito positivo e 
aggiorna Data in modo da riflettere i record appena aggiornati. Quando Reconcile 
termina, ApplyUpdates riporta il numero di errori che si sono verificati. 

In alcuni casi, il provider non e in grado di determinare come applicare gli 
aggiornamenti (ad esempio, quando applica gli aggiornamenti da una procedura 
registrata o da una join su piu tabelle). I dataset e i componenti provider client 
generano eventi che permettono di gestire queste situazioni. Pe ri dettagli, vedere 
"Interventi durante l'applicazione degli aggiornamenti". 

Se il provider e su un Application server senza stato, potrebbe essere opportuno 
cumunicare con lui a proposito delle informazioni di stato persistenti prima o dopo 
l'applicazione degli aggiornamenti. TClientDataSet riceve un evento 
BeforeApplyUpdates prima che vengano inviati gli aggiornamenti, il che consente di 
inviare al server le informazioni di stato persistenti. Dopo che gli aggiornamenti sono 
stati applicati (ma prima del processo di riconciliazione), TClientDataSet riceve un 
evento AfterApplyUpdatesin cui si puo rispondere a tutte le informazioni di stato 
persistenti restituite dall'application server. 

Interventi durante l'applicazione degli aggiornamenti 

Quando un dataset client applica gli aggiornamenti, il provider determina come 
gestire la scrittura nel server di database o nel dataset sorgente di inserimenti, 
cancellazioni e modifiche. Quando si utilizza TClientDataSet con un componente 
provider esterno, si possono utilizzare le proprieta e gli eventi di quel provider per 
influire sul modo in cui vengono applicati gli aggiornamenti. Tali proprieta ed eventi 
sono descritti in "Risposta alle richieste di aggiornamento del client" a pagina 28-8. 

Quando il provider e interno, tuttavia, come accade per qualsiasi dataset client 
associato a un meccanismo di accesso ai dati, e impossible impostarne le proprieta o 
preparare gestori di evento. Di conseguenza il dataset client pubblica una proprieta e 
due eventi che permettono di influire sul modo in cui il provider interno applica 
aggiornamenti. 

• UpdateMode controlla quali sono i campi utilizzati per individuare i record nelle 
istruzioni SQL generate dal provider per applicare gli aggiornamenti. UpdateMode 
e identico alia proprieta UpdateMode del provider. Per informazioni sulla proprieta 
UpdateMode del provider, consultare "Come influenzare la modalita di 
applicazione degli aggiornamenti" a pagina 28-10. 

• OnGetTableName permette di fornire al provider il nome della tabella di database a 
cui dovrebbe applicare gli aggiornamenti. Questo permette al provider di generare 
le istruzioni SQL per gli aggiornamenti nel caso non sia in grado di identificare la 
tabella di database in base alia query specificata mediante CommandText. Ad 
esempio, se la query esegue una join su piu tabelle che richiede l'aggiomamento di 
una singola tabella, la fornitura di un gestore di evento OnGetTableNamepermette 
al provider interno di applicare gli aggiornamenti in modo corretto. 
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Un gestore di evento OnGetTableName ha tre parametri: il componente provider 
interno, il dataset interno che ha prelevato i dati dal server e un parametro per 
restituire il nome della tabella da utilizzare nell'istruzione SQL generata. 

BeforellpdateRecord si verifica per ogni record nel pacchetto delta. Questo evento 
permette di fare tutte le modifiche dell'ultimo minuto prima che il record sia 
inserito, cancellato o modificato. Inoltre fornisce al programmatore la possibility di 
eseguire proprie istruzioni SQL per applicare l'aggiornamento nel caso in cui il 
provider non sia in grado di generare la corretta istruzione SQL (ad esempio, per 
join su piu tabelle in cui si devono aggiornare piu tabelle.) 

Un gestore di evento BeforellpdateRecord ha cinque parametri: il componente 
provider interno, il dataset interno che ha prelevato i dati dal server, un pacchetto 
delta che e posizionato sul record che sta per essere aggiornato, un'indicazione se 
l'aggiornamento e un inserimento, una cancellazione o una modifica, e infine un 
parametro che restistuisce se il gestore di evento ha eseguito o meno 
l'aggiornamento. L'utilizzo e illustrato nel seguente gestore di evento. Per 
semplicita, l'esempio assume che le istruzioni SQL siano disponibili come globali 
variabili che necessitano solo di valori di campo: 

void __fastcall TForml: : SQLClientDataSetlBeforeUpdateRecord (TObject *Sender, 

TDataSet *SourceDS, TCustomClientDataSet *DeltaDS, TUpdateKind UpdateKind, bool &Applied) 



{ 



TSQLConnection *pConn := (dynamic_cast<TCustomSQLDataSet *> (SourceDS) ->SQLConnection) 
char buffer [256] ; 
switch (UpdateKind) 
case ukModify: 

// 1st dataset: update Fields [1], use Fields [0] in where clause 
sprintf (buffer, UpdateStmtl, DeltaDS->Fields->Fields [1] ->NewValue, 

DeltaDS->Fields->Fields [0] ->01dValue) ; 
pConn->Execute (buffer, NULL, NULL); 

// 2nd dataset: update Fields [2], use Fields [3] in where clause 
sprintf (buffer, UpdateStrnt2, DeltaDS->Fields->Fields [2] ->NewValue, 

DeltaDS->Fields->Fields [3] ->01dValue) ; 
pConn->Execute (buffer, NULL, NULL); 
break ; 
case ukDelete: 
// 1st dataset: use Fields [0] in where clause 

sprintf (buffer, DeleteStmtl, DeltaDS->Fields->Fields [0] ->01dValue) ; 

pConn->Execute (buffer, NULL, NULL); 

// 2nd dataset: use Fields [3] in where clause 

sprintf (buffer, DeleteStmt2, DeltaDS->Fields->Fields [3] ->01dValue) ; 
pConn->Execute (buffer, NULL, NULL); 
break ; 
case uklnsert: 
// 1st dataset: values in Fields [0] and Fields [1] 
sprintf (buffer, UpdateStmtl, DeltaDS->Fields->Fields [0] ->NewValue, 

DeltaDS->Fields->Fields [1] ->NewValue) ; 
pConn->Execute (buffer, NULL, NULL); 
// 2nd dataset: values in Fields [2] and Fields [3] 
sprintf (buffer, UpdateStmt2, DeltaDS->Fields->Fields [2] ->NewValue, 

DeltaDS->Fields->Fields [3] ->NewValue) ; 
pConn->Execute (buffer, NULL, NULL); 
break ; 
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} 

Riconciliazione degli errori di aggiornamento 

ThereEsistono due eventi che permettono di gestire gli errori che si verificano 
durante il processo di aggiornamento: 

• Durante il processo di aggiornamento, il provider interno genera un evento 
OnllpdateError ogni volta che incontra un aggiornamento che non e in grado di 
gestire. Se si risolve il problema in un gestore di evento OnllpdateError, l'errore 
non veiene conteggiato nel numero massimo di errori passato al metodo 
Applyllpdates. Questo evento si verifica solo per i dataset client che utilizzano un 
provider interno. Se si utilizza TCHentDataSet, si puo utilizzare invece l'evento 
OnllpdateError del componente provider. 

• Dopo che l'intera operazione di aggiornamento e stata portata a termine, il dataset 
client genera un evento OnReconcileError per ogni record che il provider non e 
stato in grado di applicare al server di database. 

I gestori di evento OnReconcileError o OnllpdateError devono essere sempre definiti a 
livello di codice, anche solo per scartare i record restituiti che non e stato possibile 
riconciliare. I gestori di evento di questi due eventi funzionano alio stesso modo. Essi 
includono i seguenti parametri: 

• DataSet: Un dataset client che contiene il record aggiornato che non ha potuto 
essere applicato. E possibile usare questi metodi del dataset client per ottenere 
informazioni sui record con problemi e per modificare i record in modo da 
correggere tutti i problemi.In particolare, si devono usare le proprieta CurValue, 
OldValue e NewValue dei campi del record attivo per determinare la causa del 
problema di aggiornamento. Comunque, nel gestore di evento non di dovranno 
chiamare tutti i metodi del dataset client che modificano il record corrente. 

• E: Un oggetto rappresenta il problema verificatosi. E possibile usare questa 
eccezione per estrarre un messaggio di errore o per determinare la causa 
dell'errore di aggiornamento. 

• UpdateKind: II tipo di aggiornamento che ha generato l'errore. UpdateKind puo 
essere ukModify (il problema si e verificato aggiornando un record esistente che e 
stato modificato), uklnsert (il problema si e verificato inserendo un nuovo record), 
o ukDelete (il problema si e verificato cancellando un record esistente). 

• Action: Un parametro riferimento che permette di indicare quale azione 
intraprendere all'uscita dal gestore di evento. Nel gestore di evento questo 
parametro viene impostato per 

• Saltare questo record, lasciandolo nel registro delle modifiche. (rrSkip o raSkip) 

• Bloccare l'intera operazione di riconciliazione. (rrAbort o raAbort) 

• Incorporare la modifica che non e andata a buon fine nel corrispondente record 
dal server. (raMerge) L'operazione e possibile solo se il record del server non 
include nessuna modifica ai campi modificati nel record del dataset client. 
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• Sostituire l'attuale aggiornamento nel registro delle modifiche con il valore del 
record nel gestore di evento, che presumibilmente e stato corretto. (rrApply o 
raCorrect) 

• Ignorare l'errore completamente. (rrlgnore) Questa possibilita esiste solo nel 
gestore di evento OnUpdateError ed e destinata al caso in cui il gestore di evento 
applica raggiornamento al server di database. II record aggiornato viene 
rimosso dal registro delle modifiche e unito in Data, come se il provider avesse 
applicato l'aggiornamento. 

• Annullare le modifiche nel dataset client relativamente a questo record, 
ritornando ai valori forniti originariamente. (raCancel) Questa possibilita esiste 
solo nel gestore di evento OnReconcileError. 

• Rinnovare il valore corrente del record per farlo corrispondere al record sul 
server. (raRefresh) Questa possibilita esiste solo nel gestore di evento 
OnReconcileError. 

II codice seguente, mostra un gestore di evento OnReconcileError che usa la finestra di 
dialogo di riconciliazione degli errori, inclusa nella unit RecError presente nella 
directory dell'Object Repository. (Per utilizzare questa finestra di dialogo, includere 
nella unit del sorgente il file RecError.hpp.) 

void __fastcall TForml: :ClientDataSetReconcileError(TCustomClientDataSet *DataSet, 
EReconcileError *E, TUpdateKind UpdateKind, TReconcileAction StAction) 

{ 

Action = HandleReconcileError (this , DataSet, UpdateKind, E); 

} 

Uso di un dataset client con un provider di dati 



Un dataset client utilizza un provider per fornirlo di dati e applicare aggiornamenti 
quando 

• Memorizza in cache gli aggiornamenti da un server di database o da un altro 
dataset. 

• Rappresenta i dati in un documento XML. 

• Memorizza i dati nella parte client di un'applicazione multi-tier. 

Per qualsiasi dataset client diverso da TClientDataSet, questo provider e interno e 
pertanto non e direttamente accessibile dall'applicazione. Con TClientDataSet, il 
provider e un componente esterno che collega il dataset client con una sorgente di 
dati esterna. 

Un componente provider esterno pud risiedere nella stessa applicazione del dataset 
client oppure puo fare parte di un'applicazione separata in esecuzione su un altro 
sistema. Per ulteriori informazioni sui componenti provider, consul tare il Capitolo 
28, "Uso di componenti provider". Per maggiori informazioni sulle applicazioni in 
cui il provider e in un'applicazione separata su un altro sistema, consultare il 
Capitolo 29, "Creazione di applicazioni multi-tier". 
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Quando si utilizza un provider (interno o esterno), il dataset client memorizza 
sempre in cache qualsiasi aggiornamento. Per le informazioni relative, consultare 
"Utilizzo di un dataset client per registrare in cache gli aggiornamenti" a 
pagina 27-17. 

Le sezioni seguenti descrivono ulteriori proprieta e metodi del dataset client che gli 
permettono di operare con un provider. 

Specifica di un provider 



A differenza dei dataset client che sono associati a un meccanismo di accesso ai dati, 
TClientDataSet non ha alcun componente provider interno per assemblare i dati o 
applicare gli aggiornamenti. Se lo si vuole utilizzare per rappresentare i dati da un 
dataset sorgente o da un documento XML, sara percio necessario associare il dataset 
client a un componente provider esterno. 

II modo in cui si associa TClientDataSet a un provider dipende dal fatto che il 
provider sia nella stessa applicazione del dataset client o sia su un Application server 
remoto, in esecuzione su un altro sistema. 

• Se il provider e nella stessa applicazione del dataset client, e possibile associarlo a 
un provider nell'Object Inspector scegliendo un provider dalla lista a discesa della 
proprieta ProviderName. Questa modalita funziona finche il provider ha lo stesso 
Owner del dataset client. (II dataset client e il provider hanno lo stesso Owner se 
sono collocati sulla stessa scheda o sullo stesso modulo dati). Per utilizzare un 
provider locale che ha un Owner differente, si deve formare l'associazione in fase 
di esecuzione utilizzando il metodo SetProvider del dataset client. 

Se si prevede di passare all'utilizzo di un provider remoto o si desidera chiamare 
direttamente l'interfaccia IAppServer, e possibile anche impostare la proprieta 
RemoteServer a un componente TLocalConnection. Se si utilizza TLocalConnection, 
l'istanza di TLocalConnection gestisce la lista di tutti i provider locali 
all' applicazione e gestisce le chiamate a IAppServer del dataset client. Se non si 
utilizza TLocalConnection, l'applicazione crea un oggetto nascosto che gestisce le 
chiamate a IAppServer dal dataset client. 

• Se il provider e su un application server remoto, quindi, oltre alia proprieta 
ProviderName, e necessario specificare un componente che connette il dataset client 
all'application server. Esistono due proprieta che possono gestire questa attivita: 
RemoteServer, che specifica il nome di un componente connection da cui ottenere 
una lista di provider, oppure ConnectionBroker, che specifica un broker 
centralizzato che fornisce un ulteriore livello di indirezione fra il dataset client e il 
componente connection. II componente connection e, se utilizzato, il broker di 
connessione, risiedono nello stesso modulo dati del dataset client. II componente 
connection stabilisce e gestisce una connessione con un application server, detto 
anche "data broker". Per ulteriori informazioni, consultare "Struttura 
dell'applicazione client" a pagina 29-4. 

In progettazione, dopo aver specificato RemoteServer o ConnectionBroker, 
nell'Object Inspector si puo selezionare un provider dall'elenco a discesa della 
proprieta ProviderName. Questa lista include sia i provider locali (nella stessa 
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scheda o modulo dati) sia i provider remoti a cui e possibile accedere attraverso il 
componente connection. 

Se il componente connection e un'istanza di TDCOMConnection, l'application server 
deve essere registrato sulla macchina client. 

In esecuzione, e possibile utilizzare uno dei fornitori disponibili (locali e remoti) 
impostando da programma la proprieta ProviderName. 

Richiesta di dati da un dataset sorgente o da un documento 



I dataset client possono controllare come prelevano i propri pacchetti dati da un 
provider. Per impostazione predefinita, essi recuperano tutti i record dal dataset 
sorgente. Questo e vero sia nel caso che il dataset sorgente e il provider siano 
componenti interni (come nel caso di TBDEClientDataSet, TSQLClientDataSet e 
TIBCUentDataSet), sia nel caso che siano componenti separati che forniscono i dati a 
TCHentDataSet. 

E possibile cambiare il modo in cui il dataset client preleva i record utilizzando le 
proprieta PacketRecords e FetchOnDemand. 

Recupero incrementale 

Modificando la proprieta PacketRecords, e possibile specificare che il dataset client 
preleva i dati in lotti piu piccoli. PacketRecords specifica quanti record recuperare per 
volta, oppure il tipo di record da restituire. Per impostazione predefinita, 
PacketRecords ha come valore -1, che indica che tutti i record disponibili vengono 
recuperati contemporaneamente quando il dataset client viene aperto per la prima 
volta, o quando l'applicazione chiama in modo esplicito GetNextPacket. Quando 
PacketRecords e -1, dopo che i dati sono stati recuperati la prima volta, non e mai 
necessario che un dataset client li recuperi ulterioriormente, in quanto ha gia tutti i 
record disponibili. 

Per recuperare i record in piccoli blocchi, basta impostare PacketRecords al numero di 
record da recuperare. Per esempio, l'istruzione seguente imposta le dimensioni di 
ciascun pacchetto dati a dieci record: 

ClientDataSetl->PacketRecords = 10; 

Questa procedura di recupero dei record a blocchi viene denominato "recupero 
incrementale". I dataset client utilizzano il recupero incrementale quando 
PacketRecords e maggiore di zero. 

Per recuperare ogni lotto di record, il dataset client chiama GetNextPacket. I pacchetti 
appena recuperati vengono aggiunti alia fine dei dati gia presenti nel dataset client. 
GetNextPacket restituisce il numero di record che recupera. Se il valore restituito e 
uguale a quello di PacketRecords, non viene incontrata la fine dei record disponibili. 
Se il valore restituito e maggiore di ma minore di PacketRecords, durante 
l'operazione di recupero e stato raggiunto l'ultimo record. Se GetNextPacket 
restituisce 0, non ci sono piu record da recuperare. 

II recupero incrementale non e possibile se si stanno prelevando dati da un provider 
remoto su un Application server senza stato. Per informazioni su come utilizzare il 
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recupero incrementale in un modulo dati remoto senza stato, consultare la sezione 
"Supporto delle informazioni di stato nei moduli dati remoti" a pagina 29-20. 

E anche possibile utilizzare PacketRecords per recuperare informazioni di metadati sul 
dataset sorgente. Per recuperare le informazioni dei metadati, occorre impostare 
PacketRecords a 0. 

Recupero in automatico 

II recupero automatico dei record viene controllato dalla proprieta FetchOnDemand. 
Se FetchOnDemand e true (impostazione predefinita), il dataset client recupera 
automaticamente i record man mano che occorrono. Per disattivare questa opzione, 
basta impostare FetchOnDemand a false. Quando FetchOnDemand e false, per 
recuperare i record l'applicazione deve chiamare in modo esplicito GetNextPacket. 

Ad esempio, le applicazioni che devono rappresentare dataset a sola lettura molto 
vasti possono disattivare FetchOnDemandper avere la certezza che i dataset client 
non tentino di caricare piu dati di quanti ce ne possono stare in memoria. Tra i diversi 
recuperi il dataset client libera la sua cache utilizzando il metodo EmptyDataSet. 
Questo approccio, tuttavia, non f unziona bene quando il client deve inoltrare gli 
aggiornamenti al server. 

II provider controlla se i record nei pacchetti dati includono dati BLOB e se 
contengono dataset di dettaglio annidati. Se il provider esclude dai record queste 
informazioni, la proprieta FetchOnDemand fa si che il dataset client prenda 
automaticamente i dati BLOB e i dataset di dettaglio man mano che servono. Se 
FetchOnDemand e false e il provider non include nei record dati BLOB o dataset di 
dettaglio, per ottenere queste informazioni e necessario chiamare esplicitamente il 
metodo FetchBlobs o FetchDetails. 

Ottenimento dei parametri dal dataset sorgente 



Esistono due circostanze in cui un dataset client ha bisogno di ottenere i valori dei 
parametri: 

• L'applicazione ha la necessita di conoscere il valore dei parametri di output in una 
procedura registrata. 

• L'applicazione vuole inizializzare i parametri di input di una query o di una 
procedura registrata con i valori correnti nei dataset sorgente. 

I dataset client memorizzano valori dei parametri nella proprieta Params. Questi 
valori vengono aggiornati con i parametri di output ogni volta che il dataset client 
recupera i dati dal dataset sorgente. A volte, comunque, un componente 
TClientDataSet di un'applicazione client ha bisogno di acquisire i parametri di output 
senza dover recuperare dati. 

Per recuperare i parametri di output, pur senza recuperare record, o per inizializzare 
i parametri di input, il client pud richiedere i valori dei parametri dal dataset 
sorgente chiamando il metodo FetchParams. I parametri vengono restituiti in un 
pacchetto dati dal provider e assegnati alia proprieta Params del dataset client. 
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In fase di progettazione, la proprieta Params puo essere inizializzata facendo clic con 
il pulsante destro sul dataset client e scegliendo Fetch Params. 

Non e quasi mai necessario chiamare FetchParams quando il dataset client utilizza un 
provider interno e un dataset sorgente perche la proprieta Params rispecchia sempre i 
parametri del dataset sorgente interno. Con TClientDataSet, il metodo FetchParams (o 
il comando Fetch Params) funziona solo se il dataset client e connesso a un provider il 
cui dataset associato e in grado di fornire parametri. Ad esempio, se il dataset 
sorgente e dataset di tipo tabella non vi sono parametri da ottenere. 

Se il provider e su un sistema separate come facente parte di un Application server 
senza stato, non e possibile utilizzare FetchParams per acquisire i parametri di output. 
In un application server senza stato, altri client potrebbero modificare o rieseguire la 
query o la procedura registrata, modificando pertanto i parametri di output prima 
che avvenga la chiamata a FetchParams. Per recuperare i parametri di output da un 
application server senza stato, si deve utilizzare il metodo Execute. Se il provider e 
associato con una query o con una procedura registrata, Execute chiede al provider di 
eseguire la query o la procedura registrata e di restituire tutti i parametri di output. I 
parametri cosi restituiti vengono quindi utilizzati per aggiornare automaticamente la 
proprieta Params. 

Passaggio di parametri al dataset sorgente 



I dataset client possono passare dei parametri al dataset sorgente per specificare quali 
dati desiderano ricevere nei pacchetti dati che esso invia. Questi parametri possono 
specificare: 

• I valori dei parametri per una query o una procedura registrata che viene eseguita 
sull'application server 

• I valori di campi che limitano i record inviati nei pacchetti dati 

E possibile specificare i valori dei parametri che il dataset client invia al dataset 
sorgente sia in progettazione sia in esecuzione. In progettazione, selezionare il 
dataset client e fare doppio clic nell'Object Inspector sulla proprieta Params. Cio 
richiama il Collection editor, dove e possibile aggiungere, rimuovere o risistemare i 
parametri. Selezionando un parametro nei Collection editor, si puo usare l'Object 
Inspector per modificarne le proprieta. 

In esecuzione, per aggiungere parametri al dataset client, bisogna ricorre al metodo 
CreateParam della proprieta Params. CreateParam restituisce un oggetto parametro, 
dati un nome specifico, un tipo di parametro e un datatype. E quindi possibile 
utilizzare le proprieta di quell'oggetto parametro per assegnare un valore al 
parametro. 

Per esempio, il codice seguente aggiunge un parametro di input di nome CustNo e 
con un valore di 605: 

TParam *pParam = ClientDataSetl->Params->CreateParam(ftlnteger, "CustNo", ptlnput); 
pParam->AsInteger = 605; 
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Se il dataset client non e attivo, si possono inviare i parametri all'application server e 
recuperare un pacchetto dati che rifletta quei valori di parametro semplicemente 
impostando la proprieta Active a true. 

Invio dei parametri di una query o di una procedura registrata 

Quando la proprieta CommandType del dataset client e ctQuery o ctStoredProc, oppure, 
nel caso il dataset client sia un'istanza di TClientDataSet, quando il provider associato 
rappresenta il risultato di una query o di una procedura registrata, e possibile 
utilizzare la proprieta Paramsper specificare i valori dei parametri. Quando il dataset 
client richiede i dati dal dataset sorgente, o utilizza il suo metodo Execute per eseguire 
una query o una procedura registrata che non restituisce un dataset, passa questi 
valori di parametro insieme alia richiesta di dati o al comando da eseguire. Quando il 
provider riceve questi valori del parametro, li assegna al proprio dataset associato. 
Esso quindi incarica il dataset di eseguire la propria query o procedura registrata 
utilizzando questi valori di parametro, e, nel caso il dataset client abbia richiesto dei 
dati, inizia a fornirglieli, iniziando dal primo record nel set risultato. 

I nomi dei parametri devono coincidere con quelli utilizzati nel dataset sorgente. 

Limitazione dei record mediante parametri 

Se il dataset client e 

• un'istanza di TClientDataSet il cui provider associato rappresenta un componente 
TTable o TSQLTable, oppure 

• un'istanza di TSQLClientDataSet o di TBDEClientDataSet la cui proprieta 

CommandType e ctTable 

allora puo utilizzare la proprieta Params per limitare il numero di record che 
memorizza nella cache in memoria. Ogni parametro rappresenta un valore di campo 
che deve trovare una corrispondenza prima che il record possa essere incluso nei dati 
del dataset client. Questo funziona come un filtro, salvo che con un filtro, i record 
sono ancora memorizzati nella cache in memoria, ma non sono disponibili. 

Ogni nome di parametro deve coincidere con il nome di un campo. Se si utilizza 
TClientDataSet, questi sono i nomi dei campi nel componente TTable o TSQLTable 
associato al provider. Se si utilizza TSQLClientDataSet o TBDEClientDataSet, questi 
sono i nomi dei campi nella tabella sul server di database.I dati nel dataset client 
allora includono solo quei i record i cui valori nei campi corrispondenti coincidono 
con i valori assegnati ai parametri. 

Si consideri, per esempio, un'applicazione che visualizza gli ordini di un unico 
cliente. Quando l'utente identifica il cliente, il dataset client imposta la sua proprieta 
Params includendo un unico parametro di nome CustID (o con il nome con cui viene 
chiamato il campo nella tabella della sorgente), il cui valore identifica il cliente di cui 
verranno visualizzati gli ordini. Nel momento in cui il dataset client richiede i dati 
della sorgente dataset, passa questo valore di parametro. II provider invia, quindi, 
solo i record relativi al cliente identificato. Cio risulta molto piu efficiente rispetto al 
consentire al provider di inviare all'applicazione client tutti i record degli ordini e 
successivamente filtrare i record utilizzando il dataset client. 
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Gestione dei vincoli dal server 



Se un server di database definisce dei vincoli sulla validita dei dati, e bene che il 
dataset sia consapevole della loro esistenza. In questo modo, il dataset client puo fare 
in modo che le modifiche dell'utente non violino mai i vincoli del server .In questo 
modo, tali violaziono non saranno mai passate al server di database dove sarebbero 
rifiutate. Cio significa che vi sara un minor numero di aggiornamenti che 
genereranno condizioni di errore durante il processo di aggiornamento. 

Indipendentemente dalla sorgente dati, e possibile duplicare quei vincoli del server 
aggiungendoli esplicitamente al dataset client. Questo procedimento e descritto in 
"Specifica di vincoli custom" a pagina 27-8. 

E piu comodo, comunque, che i vincoli del server siano inclusi automaticamente nei 
pacchetti dati. In questo modo non e necessario specificare esplicitamente le 
espressioni e i vincoli predefiniti e il dataset client modifichera i valori sotto controllo 
quando cambiano i vincoli server. Per default, questo e esattamente cio che accade: se 
il dataset sorgente e a conoscenza dei vincoli del server, il provider li includera 
automaticamente nei pacchetti dati e il dataset client li imporra nel momento in cui 
l'utente registra le modifiche nel registro delle modifiche. 

Solo i dataset che utilizzano BDE possono importare i vincoli dal server. Cio significa 
che i vincoli del server sono inclusi nei pacchetti dati solo se si utilizza 
TBDEClientDataSet o TCHentDataSet con un provider che rappresenta un dataset 
basato su BDE. Per ulteriori informazioni su come importare i vincoli del server e su 
come impedire a un provider di includerli nei pacchetti dati, vedere "Gestione dei 
vincoli del server" a pagina 28-13. 

Per maggiori informazioni sulle operazioni con i vincoli, una volta che sono stati 
importati, consultare la sezione "Uso dei vincoli del server" a pagina 23-23. 

Anche se l'importazione dei vincoli e delle espressioni del server e una funzionalita 
estremamente preziosa che consente a un'applicazione di salvaguardare l'integrita 
dei dati, a volte potrebbe essere necessario disattivare temporaneamente i vincoli. Ad 
esempio, se un vincolo del server si basa sul valore massimo corrente di un campo, 
ma il dataset client utilizza il recupero incrementale, potrebbe accadere che il valore 
massimo corrente di quel campo nel dataset client sia diverso dal valore massimo sul 
server di database, e i vincoli potrebbero essere richiamati diversamente. Per fare un 
altro esempio, nel caso un dataset client applichi ai record un filtro mentre i vincoli 
sono abilitati, il filtro potrebbe interferire in modo involontario con le condizioni di 
vincolo. In ognuno di questi casi, un'applicazione potrebbe disattivare il controllo dei 
vincoli. 

Per disattivare temporaneamente i vincoli, chiamare il metodo DisableConstraints. 
Ogni volta che si chiama DisableConstraints, viene incrementato un contatore dei 
riferimenti. Finche il contatore dei riferimenti e maggiore di zero, i vincoli non 
vengono imposti sul dataset client. 

Per riattivare i vincoli sul dataset client, si deve chiamare il metodo EnableConstraints 
del dataset. Ogni chiamata a EnableConstraints decrementa il contatore dei 
riferimenti. Quando il contatore dei riferimenti e zero, i vincoli risultano nuovamente 
abilitati. 
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DisableConstraints e EnableConstraints devono essere chiamati sempre in coppia per 
essere certi che i vincoli possano essere attivati quando occorre. 

Rinnovo dei record 



Le applicazioni client lavorano con un'istantanea in memoria dei dati del dataset 
sorgente. Se il dataset sorgente rappresenta i dati di un server, man mano che il 
tempo trascorre, tali dati potrebbero essere modificati da altri utenti. I dati nel dataset 
client costituiscono una rappresentazione sempre meno precisa dei dati originali. 

Come tutti i dataset, i dataset client hanno un metodo Refresh che rinnova i propri 
record per farli corrispondere ai valori correnti sul server. Tuttavia, la chiamata a 
Refresh funziona solo se nel registro delle modifiche non c'e alcuna modifica. La 
chiamata a Refresh quando vi sono modifiche non applicate provoca un'eccezione. 

I dataset client possono anche aggiornare i dati lasciando inalterato il registro delle 
modifiche. Per fare cio, chiamare il metodo RefreshRecord. A differenza del metodo 
Refresh, RefreshRecord rinnova solo il record corrente del dataset client. RefreshRecord 
modifica il valore del record ottenuto originariamente dal provider, ma lascia le 
modifiche nel registro delle modifiche. 

Non e detto che sia sempre opportuno chiamare RefreshRecord So. le modifiche 
dell'utente entrano in conflitto con quelle apportate al dataset sottostante da altri 
utenti, la chiamata a RefreshRecord mascherera questo conflitto. Quando il dataset 
client applichera i suoi aggiornamenti, non si verificheranno errori di riconciliazione 
e l'applicazione non potra risolvere il conflitto. 

Per evitare di mascherare gli errori di aggiornamento, prima di chiamare 
RefreshRecord potrebbe essere opportuno controllare che non che non vi siano 
aggiornamenti pendenti. Ad esempio, il seguente AfterScroll aggiorna il record 
corrente ogni volta che l'utente passa su un nuovo record (garantendo il valore piu 
recente), ma solo se e possibile farlo in tutta sicurezza. 

void __fastcall TForml: :ClientDataSetlAfterScroll (TDataSet *DataSet) 

{ 

if (ClientDataSetl->UpdateStatus == usUnModified) 
ClientDataSetl->RefreshRecord() ; 

} 

Comunicazione con i provider tramite eventi custom 



I dataset client comunicano con un componente provider tramite un'interfaccia 
speciale di nome IAppServer. Se il provider e locale, IAppServer e l'interfaccia verso un 
oggetto generato automaticamente che gestisce tutta le comunicazioni fra il dataset 
client e il proprio provider. Se il provider e remoto, IAppServer e l'interfaccia di un 
oggetto COM associato di un modulo dati remoto sull'Application server, oppure 
(nel caso di un server SOAP) e un'interfaccia generata dal component connection. 

TClientDataSet offre diverse opportunity per personalizzare la comunicazione che 
usa l'interfaccia IAppServer. Prima e dopo ogni chiamata al metodo IAppServer 
indirizzata al provider del dataset client, TClientDataSet riceve speciali eventi che 
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consentono di comunicare al suo provider le informazioni piu disparate. Tali eventi 
sono abbinati ad analoghi eventi sul provider. Cosi ad esempio, quando il dataset 
client chiama il proprio metodo Applyllpdates, si verificano gli eventi seguenti: 

1 II dataset client riceve un evento Before Applyllpdates, in cui specif ica informazioni 
personalizzate arbitrarie utilizzando un Ole Variant di nome OwnerData. 

2 II provider riceve un evento Before Applyllpdates, in cui puo rispondere alle 
informazioni in OwnerData pervenute dal dataset client e aggiornare il valore di 
OwnerData con nuove informazioni. 

3 II provider prosegue il normale processo di assemblaggio del pacchetto dati 
(inclusi tutti gli eventi abbinati). 

4 II provider riceve un evento After Applyllpdates in cui puo rispondere al valore 
corrente di OwnerData e aggiornarlo con un valore da passare al dataset client. 

5 II dataset client riceve un evento After Applyllpdates, in cui puo rispondere al valore 
di OwnerData restituito. 

Tutte le altre chiamate ai metodi di IAppServer sono abbinate a set analoghi di eventi 
BeforeXXX e AfterXXX che consentono di personalizzare la comunicazione tra il 
dataset client e il provider. 

Inoltre, il dataset client possiede uno speciale metodo DataRequest il cui unico scopo e 
quello di consentire una comunicazione con il provider, specifica da applicazione ad 
applicazione. Quando il dataset client chiama DataRequest, passa come parametro un 
Ole Variant che contiene una qualsiasi informazione. A sua volta, cio genera sul 
provider un evento OnDataRequest, in cui e possibile rispondere in uno dei modi 
previsti dall'applicazione e restituire un valore al dataset client. 

Ridefinizione del dataset sorgente 



I dataset client associati a un particolare meccanismo di accesso ai dati utilizzano le 
proprieta CommandText e CommandType per specificare i dati che essi rappresentano. 
Se si utilizza TClientDataSet, tuttavia, i dati sono specificati dal dataset sorgente, non 
dal dataset client. Di solito, questo dataset sorgente ha una proprieta che specifica 
un'istruzione SQL per generare i dati, oppure il nome di una tabella di database o di 
una procedura registrata. 

Se il provider lo consente, TClientDataSet puo ridefinire la proprieta sul dataset 
sorgente che indica quali dati esso rappresenta. Cioe, se il provider lo consente, la 
proprieta CommandText del dataset client sostituisce la proprieta che specifica quali 
dati rappresenta sul dataset del provider. Cio consente a TClientDataSet di specificare 
dinamicamente quali sono dati vuole vedere. 

Per impostazione predefinita, i componenti provider esterni non permettono ai 
dataset client di utilizzare il valore di CommandText in questo modo. Per consentire a 
un TClientDataSet di utilizzare la sua proprieta CommandText, e necessario 
aggiungere poAllowCommandText alia proprieta Options del provider. In caso 
contrario, il valore di CommandText sara ignorato. 
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Non rimuovere poAllowCommandText dalla proprieta Optionsdi TSQLClientDataSet, 
TBDEClientDataSet o TIBClientDataSet. La proprieta Options del dataset client viene 
inviata al provider interno, e pertanto la rimozione di poAllowCommandText 
impedisce al dataset client di specif icare a quali dati accedere. 

II dataset client invia al provider la stringa CommandText in due occasioni: 

• Quando il dataset client si apre la prima volta. Dopo aver recuperato il primo 
pacchetto dati del provider, il dataset client non invia piu CommandText mentre 
recupera i successivi. 

• Quando il dataset client invia un comando Execute al provider. 

Per inviare un comando SQL o modificare il nome della tabella o della procedura 
registrata in un qualsiasi momento successive si deve usare esplicitamente 
l'interfaccia IAppServer che e disponibile come proprieta IAppServer. Questa proprieta 
rappresenta l'interfaccia attraverso cui il dataset client comunica con il proprio 
provider. 
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I dataset client possono operare con file dedicati su disco oltre che con dati di un 
server. Cio consente di utilizzarli in applicazioni database basate su file o che 
utilizzano il "modello briefcase". I file speciali che i dataset client utilizzano per i 
propri dati sono chiamati MyBase. 

Tutti i dataset client sono utilizzabili nelle applicazioni che seguono il modello 
briefcase, ma per un'applicazione MyBase pura (un'applicazione che non utilizza un 
provider), e preferibile utilizzare TClientDataSet, in quanta implica un minor costo 
gestionale. 

In un'applicazione MyBase, l'applicazione client non pud ottenere le definizioni di 
tabella e i dati dal server, e non esiste alcun server a cui puo applicare gli 
aggiornamenti. Invece, in modo del tutto indipendente, il dataset client deve: 

• Definire e creare le tabelle 

• Caricare i dati salvati 

• Fondere le modifiche nei dati 

• Salvare i dati 



Creazione di un nuovo dataset 



Esistono tre modi per definire e per creare dei dataset client che non rappresentano 
dati di un server: 

• E possibile definire e creare un nuovo dataset client utilizando i campi persistenti 
o le definizioni dei campi e degli indici. Questo segue lo stesso schema della 
creazione di un qualsiasi dataset di tipo tabella. Per ulteriori informazioni 
consultare "Creazione e cancellazione di tabelle" a pagina 22-40. 
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• E possibile copiare un dataset esistente (in progettazione o in esecuzione). Per 
maggiori informazioni sulla copia di dataset esistenti, consultare il paragrafo 
"Copia di dati da un altro dataset" a pagina 27-15. 

• E possibile creare un dataset client da un qualsiasi documento XML. Per i dettagli, 
vedere "Conversione di documenti XML in pacchetti dati" a pagina 30-6. 

Una volta creati il dataset, e possibile salvarlo in un file. Da questo momento in poi, 
non sara piu necessario ricreare la tabella, ci si limitera a caricarla dal file salvato. 
Quando si inizia un'applicazione database basata su file, prima di iniziare a scrivere 
l'applicazione stessa, sarebbe oppurtuno per prima cosa creare e salvare i file vuoti 
per i dataset. In questo modo, si inizia con i metadati per il dataset client gia definite 
semplificando cosi la configurazione dell'interfaccia utente. 

Caricamento dei dati da un file o da uno stream 



Per caricare i dati da un file, si deve chiamare il metodo LoadFromFile di un dataset 
client. LoadFromFile richiede un solo parametro, una stringa che specifica il file da cui 
leggere i dati. II nome del file deve essere, se occorre, completo di percorso. Se si 
caricano sempre i dati del dataset client dallo stesso file, si pud invece utilizzare la 
proprieta FileName. Se FileName contiene un file esistente, i dati vengono caricati 
automaticamente non appena viene aperto il dataset client. 

Per caricare i dati da uno stream, si deve chiamare il metodo LoadFromStream del 
dataset client. LoadFromStream richiede un solo parametro, un oggetto stream che 
fornisce i dati. 

I dati caricati tramite LoadFromFile (LoadFromStream) devono essere stati 
precedentemente salvati utilizzando un formato dati del dataset client da questo o da 
un altro dataset client con il metodo SaveToFile (SaveToStream), opppure generati a 
parire da un documento XML. Per ulteriori informazioni sul salvataggio dei dati in 
un file o in uno stream, consultare il paragrafo "Salvataggio dei dati in un file o in 
uno stream" a pagina 27-37. Per informazioni sulla creazione di dati di dataset client 
a partire da un documento XML, vedere il Capitolo 30, "Uso di XML nelle 
applicazioni database". 

Quando si chiama LoadFromFile o LoadFromStream, tutti i dati del file vengono letti 
nella proprieta Data. Tutte le modifiche che erano presenti nel relativo registro 
quando i dati sono stati salvati vengono letti nella proprieta Delta. Tuttavia, gli unici 
indici che vengono letti dal file sono quelli che sono stati creati con il dataset. 

Fusione delle modifiche nei dati 



Quando si apportano modifiche a un dataset client, tutte le modifiche ai dati esistono 
solo in un registro delle modifiche in memoria. Questo file di registrazione puo 
essere gestito separatamente dai dati stessi, benche sia completamente trasparente 
agli oggetti che utilizzano il dataset client. Vale a dire, ad esempio, che i controlli che 
consentono di spostarsi nel dataset client o ne visualizzano i dati vedono una vista 
dei dati che include le modifiche. Se non si desidera annullare le modifiche, tuttavia, 
si dovrebbe unire il registro delle modifiche nei dati del dataset client chiamando il 
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metodo MergeChangeLog. MergeChangeLog sovrascrive i record in Data con i valori di 
campo modificati presenti nel registro delle modifiche. 

Dopo l'esecuzione di MergeChangeLog, Data contiene un misto di dati esistenti e delle 
modifiche che si trovavano nel registro. Questa miscela diventa la nuova struttura di 
Data alia quale possono essere apportate ulteriori modifiche. MergeChangeLog 
rimuove dal registro delle modifiche tutti i record e riporta la proprieta ChangeCount 
aO. 

Non chiamare MergeChangeLog per i dataset client che utilizano un provider. In 
questo caso, per scrivere le modifiche nel database si deve chiamare Applyllpdates. 
Per ulteriori informazioni, consultare "Applicazione degli aggiornamenti" a 
pagina 27-22. 

E anche possibile fondere le modifiche nei dati di un dataset client diverso se questo 
originariamente ha fornito i dati nella proprieta Data. Per ottenere questo risultato, 
occorre utilizzare un dataset provider. Per un esempio su come farlo, consultare 
"Assegnazione diretta dei dati" a pagina 27-15. 

Se non si vogliono utilizzare le funzionalita estese di annullamento del registro delle 
modifiche, e possibile impostare la proprieta LogChanges del dataset client a false. 
Quando LogChanges e false, le modifiche vengono combinate automaticamente 
quando si registrano i record e non c'e necessita di chiamare MergeChangeLog. 

Salvataggio dei dati in un file o in uno stream 

Anche dopo aver unito le modifiche nei dati del dataset client, questi dati esistono 
ancora solo in memoria. Benche siano persistenti, se si chiude il dataset client e lo si 
riapre nell'applicazione, tali dati scompariranno nel momento in cui si chiude 
l'applicazione. Per rendere i dati permanenti, devono essere scritti sul disco. Scrivere 
le modifiche sul disco utilizzando il metodo SaveToFile. 

SaveToFile richiede un solo parametro, una stringa che specifica il file in cui scrivere i 
dati. II nome del file deve essere, se occorre, completo di percorso. Se il file esiste gia, 
il suo contenuto viene completamente sovrascritto. 

SaveToFile non salvaguarda gli indici eventualmente aggiunti al dataset client in 
esecuzione, ma solo gli indici aggiunti al momento della creazione del dataset client. 

Se si salvano sempre i dati nello stesso file, si puo invece ricorre alia proprieta 
FileName. Se FileName e impostata, i dati vengono salvati automaticamente nel file 
indicato quando il dataset client viene chiuso. 

E anche possibile salvare i dati in uno stream utilizzando il metodo SaveToStream. 
SaveToStream richiede un solo parametro, un oggetto stream che riceve i dati. 

Se si salva un dataset client mentre ci sono ancora modifiche nel relativo registro, 
queste non vengono fuse con i dati. Quando si ricaricano i dati, utilizzando il metodo 
LoadFromFile o LoadFromStream, il registro delle modifiche conterra ancora le 
modifiche che non sono state fuse. Cio e importante per le applicazioni che 
sopportano il modello briefcase, nel quale quelle modifiche devono magari essere 
applicate a un componente provider nell'application server. 
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Capitolo 




Uso di componenti provider 

I componenti provider (TDataSetProvider e TXMLTransformProvider) forniscono il 
meccanismo in base al quale i dataset client ottengono i loro dati. I provider 

• Ricevono le richieste di dati da un dataset client (o da un broker XML), prelevano i 
dati richiesti, assemblano i dati in un pacchetto dati trasportabile e restituiscono i 
dati al dataset client (o al borker XML). Questa attivita viene definita "fornitura." 

• Ricevono i dati aggiornati da un dataset client (o da un broker XML), applicano gli 
aggiornamenti al server di database o al dataset sorgente o al documento sorgente 
XML e registrano tutti gli aggiornamenti che non possono essere applicati, 
restituendo gli aggiornamenti insoluti al dataset client per una ulteriore 
riconciliazione. Questa attivita viene definita "risoluzione." 

Quasi tutto il lavoro di un componente provider viene svolto automaticamente. Non 
e necessario scrivere alcun programma sul provider per creare i pacchetti dati a 
partire dai dati in un dataset o in un documento XML o per applicare gli 
aggiornamenti. Tuttavia, i componenti provider includono un numero di eventi e 
proprieta che consentono all'applicazione un controllo piu diretto su quali 
informazioni inserire nei pacchetti da inviare al client e sulla modalita di risposta 
dell'applicazione alle richieste del client. 

Quando si utilizza TBDEClientDataSet, TSQLClientDataSet o TIBCHentDataSet, il 
provider e interno al dataset client e l'applicazione non ha alcun accesso diretto a 
esso. Quando si utilizza TClientDataSet o TXMLBroker, invece, il provider e un 
componente separato che e possibile utilizzare per controllare quali informazioni 
vengono assemblate in pacchetti per i client e per rispondere agli eventi che si 
verificano durante il processo di fornitura e di risoluzione. I dataset client che hanno 
un provider interno fanno emergere alcune proprieta ed eventi del provider interno 
come se fossero proprieta ed eventi propri del dataset, ma per un maggiore controllo, 
si potrebbe preferire l'utilizzo di TClientDataSet con un componente provider 
separato. 
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Individuazione della sorgente dati 

Quando si utilizza un componente provider separate tale componente puo risiedere 
nella stessa applicazione del dataset client (o del broker XML) oppure puo risiedere 
in un application server come parte di un' applicazione multi-tier. 

Questo capitolo descrive come utilizzare un componente provider per controllare 
l'interazione con i dataset client o con i broker XML. 

Individuazione della sorgente dati 



Quando si utilizza un componente provider, occorre specificare la sorgente che esso 
utilizza per ottenere i dati che assemblera in pacchetti dati. A seconda della versione 
di C++Builder, e possibile specificare la sorgente come segue: 

• Per fornire i dati a partire da un dataset, utilizzare TDataSetProvider. 

• Per fornire i dati a partire da un documento XML, utilizzare 
TXMLTransformProvider. 

Uso di un dataset come sorgente dati 



Se il provider e un provider di dataset (TDataSetProvider), impostare la proprieta 
DataSet del provider indicando il nome del dataset da utilizzare. In fase di 
progettazione, selezionare nell'Object Inspector uno dei datasets disponibili 
nell'elenco a discesa della proprieta DataSet. 

TDataSetProvider interagisce con il dataset sorgente utilizzando l'interfaccia 
IProvider Support. Questa interfaccia e resa disponibile da TDataSet, ed e percio 
disponibile per tutti i dataset. Tuttavia, i metodi di IProviderSupport implementati in 
TDataSet sono soprattutto stub il cui unico compito e quello di sollevare eccezioni. 

Le classi dataset fornite con C++Builder (i dataset BDE, i dataset ADO, i dataset 
Client, i dataset dbExpress e i dataset Interbase Express) ridefiniscono questi metodi 
per implementare l'interfaccia IProviderSupport in modo piu proficuo. I dataset client 
non aggiungono niente all'implementazione ereditata di IProviderSupport, ma 
possono essere ancora utilizzati come un dataset sorgente purche la proprieta 
ResolveToDataSet del provider sia impostata a true. 

Gli autori di componenti che creano propri discendenti custom a partire da TDataSet, 
nel caso i dataset debbano fornire i dati a un provider, devono ridefinire tutti i 
metodi appropriati di IProviderSupport. Se il provider si limita a fornire pacchetti dati 
con operazioni di sola lettura (ovvero, se non applica aggiornamenti), i metodi di 
IProviderSupport implementati in TDataSet possono essere sufficienti. 

Uso di un documento XML come sorgente dati 



Se il provider e un provider XML, impostare la proprieta XMLDataFile del provider 
per indicare il documento di origine. 

I provider XML devono trasformare il documento di origine in pacchetti dati, 
cosicche oltre all'indicazione del documento di origine, si deve anche specificare 
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come trasformare quel documento in pacchetti dati. Questa trasformazione e gestita 
dalla proprieta TransformRead del provider. TransformRead rappresenta un oggetto 
TXMLTransform. E possibile impostarne le proprieta per specificare quale 
trasformazione utilizzare e utilizzarne gli eventi per fornire il proprio input alia 
trasformazione. Per ulteriori informazioni sull'utilizzo di provider XML, consultare 
"Impiego di un documento XML come origine di un provider" a pagina 30-8. 



Comunicazione con il dataset clientt 



Tutte le comunicazioni fra un provider e un dataset client o un broker XML 
avvengono attraverso un'interfaccia IAppServer. Se il provider e nella stessa 
applicazione del client, questa interfaccia viene implementata da un oggetto nascosto 
generato automaticamente, o da un componente TLocalConnection. Se il provider fa 
parte di un'applicazione multi-tier, questa e l'interfaccia del server dell'applicazione 
oppure (in caso di server SOAP) un'interfaccia generata dal componente connection. 

La maggior parte delle applicazioni non utilizzano IAppServerdirettamente, ma lo 
richiamano indirettamente attraverso le proprieta e i metodi del dataset client o del 
broker XML. Tuttavia, se occorre, e possibile effettuare chiamate dirette all'interfaccia 
App 'Server utilizzando la proprieta AppServerdel dataset client. 

La Tabella 28.1 elenca i metodi dell'interfaccia IAppServer e i metodi e gli eventi 
corrispondenti del componente provider e del dataset client. Questi metodi di 
IAppServer includono un parametro Provider. Nelle applicazioni multi-tier, questo 
parametro indica il provider sull'application server con cui il dataset client comunica. 
Molti metodi includono anche un parametro Ole Variant di nome OwnerDatache 
permette a un dataset client e a un provider di passarsi informazioni custom. Per 
impostazione predefinita OwnerData non e utilizzato, ma viene passato a tutti i 
gestori di evento rendendo possibile la scrittura di codice che permetta al provider di 
adattarsi alle informazioni definite dall'applicazione prima e dopo ogni chiamata da 
parte di un dataset client. 

Tabella 28.1 Membri dell'interfaccia AppServer 



IAppServer 

Metodo AS_Apply Up dates 

Metodo ASJDataRequest 
Metodo AS_Execute 

Metodo AS_GetParams 

Metodo 

AS_GetProviderNames 



Componente Provider 

Metodo ApplyUpdates, 
evento BeforeApplyUpdates, 
evento AfterApplyUpdates 

Metodo DataRequest, 
evento OnDataRequest 

Metodo Execute, 
evento BeforeExecute, 
evento AfterExecute 

Metodo GetParams, 
evento BeforeGetParams, 
evento AfterGetParams 

Utilizzato per identificare 
tutti i provider disponibili. 



TCIientDataSet 

Metodo ApplyUpdates, 
evento BeforeApplyUpdates, 
evento AfterApplyUpdates. 

Metodo DataRequest. 

Metodo Execute, 
evento BeforeExecute, 
evento AfterExecute. 

Metodo FetchParams, 
evento BeforeGetParams, 
evento AfterGetParams. 

Utilizzato per creare una lista da 
usare in progettazione per la 
proprieta ProviderName. 
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Tabella 28.1 Membri dell'interfaccia AppServer 



lAppServer 

Metodo AS_GetRecords 



Metodo AS_RowRequest 



Componente Provider 

Metodo GetRecords, 
evento BeforeGetRecords, 
evento AfterGetRecords 



Metodo RowRequest, 
evento BeforeRowRequest, 
evento AfterRowRequest 



TCIientDataSet 

Metodo GetNextPacket, 
proprieta Data, 
evento BeforeGetRecords, 
evento AfterGetRecords 

Metodo FetchBlobs, 
Metodo FetchDetails, 
Metodo RefreshRecord, 
evento BeforeRowRequest, 
evento AfterRowRequest 



Come applicare gli aggiornamenti usando un provider di dataset 



I componenti TXMLTransformProvider applicano sempre gli aggiornamenti al 
documento XML associate Quando si utilizza TDataSetProvider, tuttavia, e possibile 
scegliere come applicare gli aggiornamenti. Per impostazione predefinita, quando i 
componenti TDataSetProvider applicano aggiornamenti e risolvono gli errori di 
aggiornamento, comunicano direttamente col server di database utilizzando 
istruzioni SQL generate dinamicamente. II vantaggio offerto da questo metodo sta 
nel fatto che l'applicazione server non deve combinare gli aggiornamenti due volte 
(prima sul dataset e quindi sul server remoto). 

Tuttavia, non e detto che si voglia utilizzare sempre questo approccio. Per esempio, 
potrebbe essere necessario utilizzare alcuni eventi del componente dataset. Oppure, 
il dataset utilizzato potrebbe non supportare l'uso di istruzioni SQL (per esempio, se 
si stanno fornendo dati da un componente TCIientDataSet). 

TDataSetProvider consente di decidete se applicare gli aggiornamenti al server di 
database, utilizzando istruzioni SQL, o al dataset sorgente, impostando la proprieta 
ResolveToDataSet. Se questa proprieta e impostata a true, gli aggiornamenti vengono 
applicati al dataset. Se e impostata a false, gli aggiornamenti vengono applicati 
direttamente al server di database associato. 



Controllo delle informazioni incluse nei pacchetti dati 



Operando con un provider di dataset, esistono diversi modi per controllare quali 
informazioni vengono incluse nei pacchetti dati trasmessi e ricevuti dal client. Questi 
includono 

• Specifica dei campi inclusi in un pacchetto dati 

• Impostazione di opzioni che influenzano i pacchetti dati 

• Aggiunta di informazioni personali al pacchetto dati 

Queste tecniche per il controllo del contenuto di pacchetti dati sono disponibili solo 
per i provider di dataset. Quando si utilizza TXMLTransformProvider, e possibile 
controllare il contenuto dei pacchetti dati solo controllando il file di trasformazione 
utilizzato dal provider. 
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Specifica dei campi inclusi in un pacchetto dati 



Operando con un provider di dataset, e possibile controllare quali campi sono inclusi 
nei pacchetti dati mediante la creazione di campi persistenti nel dataset utilizzato dal 
provider per generare i pacchetti dati. II provider includera quindi solamente questi 
campi. Possono essere inclusi anche i campi il cui valore viene generato 
dinamicamente dal dataset sorgente (come i campi calcolati o i campi di 
consultazione), ma appaiono ai dataset client sul lato ricevente come campi statici a 
sola lettura. Per informazioni sui campi persistenti, consultare "Componenti campo 
persistenti" a pagina 23-3. 

Se i dataset client dovranno modificare i dati e applicare gli aggiornamenti, sara 
necessario includere un numero sufficiente di campi in modo da non avere record 
duplicati nel pacchetto dati. In caso contrario, quando si applicheranno gli 
aggiornamenti, sara impossibile determinare quale record aggiornare. Se si vuole 
evitare che il dataset client possa vedere o utilizzare quei campi aggiuntivi, forniti al 
solo scopo di grantire l'unicita dei record, impostare la proprieta ProviderFlags di quei 
campi in modo da includere pfHidden. 

L'inclusione di un numero di campi sufficiente ad evitare record duplicati e da 
prendere in considerazione anche quando il dataset sorgente del provider 
rappresenta una query. Si deve specificare la query in modo da includere abbastanza 
campi da rendere i record unici, anche se l'applicazione non utilizza tutti i campi. 



Impostazione di opzioni che influenzano i pacchetti dati 



La proprieta Options di un provider di dataset consente di specificare, in fase di 
trasmissione di BLOB o di tabelle di dettaglio annidate, se includere proprieta di 
visualizzazione dei campi, che tipi di aggiornamenti sono consentiti e cosi via. La 
tabella seguente elenca i possibili valori che possono essere inclusi in Options. 



Tabella 28.2 Opzione del provider 
Valore 

poAutoRefresh 



poReadOnly 
poDisableEdits 



poDisablelnserts 



poDisableDeletes 



Significato 

II provider aggiorna il dataset client con i valori di record 
correnti non appena ha applicato gli aggiornamenti. 

II dataset client non puo applicare gli aggiornamenti al provider. 

I dataset client non possono modificare i valori dei dati esistenti. 
Se l'utente prova a modificare un campo, il dataset client solleva 
un'eccezione. (Questo non influisce sulla capacita del dataset 
client di inserire o di cancellare record). 

I dataset client non possono inserire nuovi record. Se l'utente 
prova a inserire un nuovo record, il dataset client solleva 
un'eccezione. (Questo non influisce sulla capacita del dataset 
client di cancellare i record o di modificare i dati esistenti) 

I dataset client non possono cancellare record. Se l'utente prova a 
cancellare un record, il dataset client solleva un'eccezione. 
(Questo non influisce sulla capacita del dataset client di inserire 
o di modificare record) 
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Tabella 28.2 Opzione del provider 
Valore 

poFetchBlobsOnDemand 



poFetchDetailsOnDemand 



poIncFieldProps 



poCascadeDeletes 



poCascadeUpdates 



poAllowMultiRecordUpdates 



poNoReset 
poPropogateChanges 

poAllowCommandText 

poRetainServerOrder 



Significato 

I valori dei campi BLOB non sono inclusi nel pacchetto 
dati.Invece, i dataset client devono richiedere questi valori man 
mano che occorrono. Se la proprieta FetchOnDemand del dataset 
client e true, il dataset client richiede questi valori 
automaticamente. Altrimenti, l'applicazione deve chiamare il 
metodo FetchBlobs del dataset client per reperire i dati BLOB. 

Quando il dataset del provider rappresenta il master in una 
relazione master /detail, i valori annidati di dettaglio non sono 
inclusi nel pacchetto dati. Invece, i dataset client richiedono 
questi valori man mano che occorrono. Se la proprieta 
FetchOnDemand del dataset client e true, il dataset client richiede 
questi valori automaticamente. Altrimenti, l'applicazione deve 
chiamare il metodo FetchDetails del dataset client per reperire i 
dettagli annidati. 

II pacchetto dati include, se possibile, le seguenti proprieta di 
campo: Alignment, DisplayLabel, DisplayWidth, Visible, 
DisplayFormat, EditFormat, MaxValue, MinValue, Currency, 
EditMask, DisplayValues. 

Quando il dataset del provider rappresenta il master in una 
relazione master /detail, il server cancella automaticamente i 
record di dettaglio quando vengono cancellati i record 
principali. Per usare questa opzione, il database server deve 
essere impostato per eseguire cancellazioni in cascata come parte 
della sua integrita referenziale. 

Quando il dataset del provider rappresenta il master in una 
relazione master /detail, i valori chiave delle tabelle di dettaglio 
vengono automaticamente aggiornati quando vengono 
modificati i valori corrispondenti nei record del master. Per 
usare questa opzione, il database server deve essere impostato 
per eseguire aggiornamenti in cascata come parte della sua 
integrita referenziale. 

Un singolo aggiornamento puo provocare la modifica di piu 
record della tabella di database sottostante. Questo 
comportamento puo essere il risultato di trigger, dell'integrita 
referenziale, di istruzioni SQL sul dataset sorgente, e cosi via. Si 
noti che, nel caso si verifichi un errore, i gestori di evento 
consentono l'accesso al record che e stato aggiornato, ma non 
agli altri record modificati di conseguenza. 

I dataset client non possono specificare che il provider dovrebbe 
riposizionare il cursore sul primo record prima di reperire i dati. 

Le modifiche apportate dal server ai record aggiornati durante il 
processo di aggiornamento vengono ritrasferite al client e 
combinate nel dataset del client. 

II client puo ridefinire il testo del comando SQL associato del 
dataset o il nome della tabella o la procedura registrata che esso 
rappresenta. 

II dataset client non dovrebbe riordinare i record nel dataset per 
imporre un ordine predefinito. 
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Controllo delle informazioni incluse nei pacchetti dati 

Aggiunta di informazioni personali ai pacchetti dati 



Usando l'evento OnGetDataSetProperties, i provider di dataset possono aggiungere ai 
pacchetti dati informazioni definite dall'applicazione. Queste informazioni vengono 
codificate come OleVariant, e memorizzate con un nome specificate I dataset client 
possono quindi recuperare le informazioni usando il loro metodo GetOptionalParam. 
E anche possibile specificare di includere le informazioni nei pacchetti delta che il 
dataset client invia quando vengono aggiornati i record. In questo caso, il dataset 
client puo non essere mai a conoscenza delle informazioni, ma il provider puo 
inviare a se stesso un messaggio con ritorno. 

Quando nell'evento OnGetDataSetProperties si aggiungono informazioni personali, 
ogni singolo attributo (a volta chiamato "parametro facoltativo") viene specificato 
usando un array Variant che contiene tre elementi: il nome (una stringa), il valore (un 
Variant), e un flag booleano che indica se le informazioni devono essere incluse nei 
pacchetti delta quando il client applica gli aggiornamenti.Creando un array Variant 
di array Variant, si possono aggiungere piu attributi. Per esempio, il seguente gestore 
di evento OnGetDataSetProperties invia due valori, l'ora in cui i dati sono stati forniti e 
il numero totale di record del dataset sorgente. Quando i dataset client applicano gli 
aggiornamenti, vengono restituite solo le informazioni relative all'ora in cui i dati 
sono stati forniti: 

void __fastcall TMyDataModulel: :ProviderlGetDataSetProperties (TObject *Sender, TDataSet 

*DataSet, out OleVariant Properties) 

{ 

int ArrayBounds [2] ; 
ArrayBounds [0] = 0; 
ArrayBounds [1] = 1; 

Properties = VarArrayCreate (ArrayBounds, 1, varVariant ) ; 
Variant values [3] ; 

values [0] = Variant ( "TimeProvided" ) ; 
values [1] = Variant (Now() ) ; 
values[2] = Variant (true) ; 
Properties [0] = VarArrayOf( values, 2) ; 
values[0] = Variant ("TableSize") ; 
values [1] = Variant (DataSet->RecordCount) ; 
values[2] = Variant (false) ; 
Properties [1] = VarArrayOf (values, 2) ; 

} 

Quando il dataset client applica gli aggiornamenti, l'ora in cui sono stati forniti i 
record originali puo essere letta nell'evento OnUpdateData del provider: 

void _fastcall TMyDataModulel: : Provider lUpdateData (TObject *Sender, TCustomClientDataSet 
*DataSet) 

{ 

Variant WhenProvided = DataSet->GetOptionalParam( "TimeProvided" ) ; 

} 
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Risposta alle richieste di dati del client 



Solitamente le richieste di dati da parte del client vengono gestite automaticamente. 
Un dataset client o un broker XML richiede un pacchetto dati chiamando GetRecords 
(in modo indiretto, mediante l'interfaccia IAppServer). II provider risponde 
automaticamente prelevando i dati dal dataset o dal documento XML associate 
creando un pacchetto dati e inviandolo al client. 

II provider ha la facolta di modificare i dati dopo che sono stati assemblati in un 
pacchetto, ma prima che il pacchetto venga inviato al client. Per esempio, si potrebbe 
voler rimuovere i record dal pacchetto in base a determinati criteri (come il livello di 
accesso dell'utente), o, in un'applicazione multi-tier, si potrebbe voler crittografare 
dati particolarmente delicati prima che siano inviato al client. 

Per effettuare l'editing del pacchetto dati prima di inviarlo al client, occorre scrivere 
un gestore di evento OnGetData event handler. II gestore di evento OnGetData 
fornisce il pacchetto dati come un parametro sotto forma di dataset client. Usando i 
metodi di questo dataset client, e possibile modificare i dati prima di inviarli al client. 

Come per tutte le chiamate ai metodi effettuate tramite l'interfaccia IAppServer, il 
provider ha la possibility di comunicare informazioni di stato persistenti con un 
dataset client prima e dopo la chiamata a GetRecords. Questa comunicazione avviene 
utilizzando i gestori di evento BeforeGetRecords e AfterGetRecords. Per una trattazione 
delle informazioni di stato persistenti negli application server, consultare "Supporto 
delle informazioni di stato nei moduli dati remoti" a pagina 29-20. 

Risposta alle richieste di aggiornamento del client 



Un provider applica gli aggiornamenti ai record del database sulla base di un 
pacchetto dati Delta ricevuto da un dataset client o da un broker XML. II client 
richiede gli aggiornamenti chiamando il metodo Applyllpdates (in modo indiretto, 
mediante l'interfaccia IAppServer). 

Come per tutte le chiamate ai metodi effettuate tramite l'interfaccia IAppServer, il 
provider ha la possibility di comunicare informazioni di stato persistenti con un 
dataset client prima e dopo la chiamata a Applyllpdates. Questa comunicazione 
awiene utilizzando i gestori di evento BeforeApplyllpdates e After Applyllpdates. Per 
una trattazione delle informazioni di stato persistenti negli application server, 
consultare "Supporto delle informazioni di stato nei moduli dati remoti" a 
pagina 29-20. 

Se si utilizza un provider di dataset, sono disponibili molti altri eventi che 
consentono un maggore controllo: 

Quando un provider di dataset riceve una richiesta di aggiornamento, genera un 
evento OnllpdateData, in cui e possibile modificare il pacchetto Delta prima che 
venga scritto nei dataset o che influenzi il modo in cui vengono applicati gli 
aggiornamenti. Dopo l'evento OnllpdateData, il provider scrive le modifiche nei 
database o nei dataset sorgente. 
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II componente provider esegue l'aggiomamento record per record. Prima di 
applicare gli aggiornamenti a ciascun record, il provider genera un evento 
BeforellpdateRecord, con il quale e possibile vagliare gli aggiornamenti prima che 
vengano applicati. Se si verifica un errore durante l'aggiornamento di un record, il 
provider riceve un evento OnllpdateError in cui pud risolvere l'errore. Solitamente, 
gli errori si verificano perche la modifica non rispetta un vincolo del server o perche 
il record del database e stato modificato da un'applicazione differente in una fase 
successiva al suo recupero da parte del provider, ma prima della richiesta del dataset 
client di applicare gli aggiornamenti. 

Gli errori di aggiornamento possono essere elaborati dal provider di dataset o dal 
dataset client. Se il provider fa parte di un'applicazione multi-tier dovrebbe gestire 
tutti gli errori di aggiornamento che non richiedono un'interazione con l'utente per la 
loro risoluzione. Se il provider non riesce a risolvere una condizione di errore, 
memorizza temporaneamente una copia del record che ha problemi. Completata 
l'elaborazione del record il provider restituisce al dataset client il numero di errori 
incontrati e copia i record non risolti in un pacchetto risultato che viene restituito al 
dataset client per un'ulteriore riconciliazione. 

I set di aggiornamenti vengono trasmessi ai gestori di evento di tutti gli eventi del 
provider come dataset client. Se il gestore di evento si occupa solo di alcuni tipi di 
aggiornamenti, e possibile filtrare il dataset in base alio stato di aggiornamento dei 
record. Filtrando i record, il gestore di evento non deve riordinare i record che non 
utilizzera. Per filtrare il dataset client in base alio stato di aggiornamento dei suoi 
record, impostare la sua proprieta StatusFilter. 

Le applicazioni devono fornire un supporto piu efficace nel caso in cui gli 
aggiornamenti siano indirizzati su un dataset che non rappresenta una singola 
tabella. Per i dettagli sulle operazioni da compiere, consultare la sezione 
"Applicazione di aggiornamenti a dataset che non rappresentano una singola 
tabella" a pagina 28-12. 

Modifica dei pacchetti delta prima dell'aggiornamento del database 



Prima di applicare gli aggiornamenti al database, esso genera un evento 
OnllpdateData. II gestore di evento OnllpdateData riceve una copia del pacchetto 
Delta come parametro. Questo e un dataset client. 

Nel gestore di evento OnllpdateData si puo usare qualsiasi proprieta e metodo del 
dataset client per modificare il pacchetto Delta prima che venga scritto nel dataset. 
Una proprieta particolarmente utile e UpdateStatus. UpdateStatus indica quale tipo di 
modifica rappresenta il record corrente del pacchetto delta. Puo assumere uno dei 
valori elencati nella Tabella 28.3. 

Tabella 28.3 Valori di UpdateStatus 
Valore Descrlzione 

usUnmodified II contenuto del record non e stato modificato 

usModified II contenuto del record e stato modificato 
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Tabella 28.3 Valori di UpdateStatus 



Valore 


Descrizione 


uslnserted 


11 record e stato inserito 


usDeleted 


11 record e stato cancellato 



Per esempio, il seguente gestore di evento OnllpdateData inserisce la data corrente in 
ogni nuovo record inserito nel database: 

void __fastcall TMyDataModulel: : Provider lUpdateDatafTObject *Sender, TCustomClientDataSet 
*DataSet) 

{ 

DataSet->First () ; 
while ( !DataSet->Eof ) 

{ 

if (DataSet->UpdateStatus == uslnserted) 
{ 

DataSet->Edit() ; 

DataSet->FieldByName("DateCreated")->AsDateTime = Dated; 
DataSet->Post () ; 

} 

DataSet->Next d ; 

} 

} 

Come influenzare la modalita di applicazione degli aggiornamenti 



L'evento OnllpdateData da al provider di dataset anche la possibility di indicare come 
i record del pacchetto delta vengono applicati al database. 

Per impostazione predefinita, le modifiche nel pacchetto delta vengono scritte nel 
database usando istruzioni SQL di tipo UPDATE, INSERT o DELETE generate 
automaticamente; ad esempio 

UPDATE EMPLOYEES 

set EMPNO = 748, NAME = 'Smith 1 , TITLE = 'Programmer 1', DEPT = 52 
WHERE 

EMPNO = 748 and NAME = 'Smith' and TITLE = 'Programmer 1' and DEPT = 47 

Se non specificato diversamente, tutti i campi dei record del pacchetto delta vengono 
inclusi nella clausola UPDATE e nella clausola WHERE. Tuttavia, puo essere 
opportuno escludere alcuni di questi campi. Un modo per farlo consiste 
nell'impostare la proprieta UpdateMode del provider. Alia proprieta UpdateMode puo 
essere assegnato uno dei seguenti valori: 



Tabella 28.4 Valori di UpdateMode 




upWhereAll Tutti i campi vengono usati per individuare i campi (clausola WHERE). 

up WhereChanged Per individuare i record vengono usati solo i campi chiave e i campi che 
sono stati modificati. 

upWhereKeyOnly Per individuare i record vengono usati solo i campi chiave. 
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Potrebbe, comunque, essere necessario anche un maggiore controllo. Per esempio, 
con l'istruzione precedente si potrebbe voler impedire la modifica del campo 
EMPNO escludendolo dalla clausola UPDATE ed escludere dalla clausola WHERE i 
campi TITLE e DEPT per evitare conflitti di aggiornamento nel caso altre 
applicazioni abbiano modificato i dati. Per specificare le clausole in cui appare un 
certo campo, si deve usare la proprieta Provider Flags. ProviderFlags e un set che puo 
includere uno dei valori elencati nella Tabella 28.5 



Tabella 28.5 Valori di ProviderFlags 
Valore Descrizione 

pfln Where II campo appare nella clausola WHERE delle istruzioni INSERT, DELETE e 

UPDATE generate quando UpdateMode e upWhereAll oppure upWhereChanged. 

pflnUpdate II campo appare nella clausola UPDATE delle istruzioni UPDATE generate. 

pflnKey II campo viene usato nella clausola WHERE delle istruzioni generate quando 

UpdateMode e upWhereKeyOnly. 

pfHidden II campo viene incluso nei record per assicurare l'univocita, ma non puo essere 
visto o usato sul lato client. 



Cosi, il seguente gestore di evento OnUpdateData permette di aggiornare il campo 
TITLE e utilizza i campi EMPNO e DEPT per individuare il record chiesto. Se si 
verifica un errore, e viene fatto un secondo tentativo per individuare il record 
solamente in base alia chiave, il comando SQL generato cerchera solo il campo 
EMPNO: 

void __fastcall TMyDataModulel: : Provider lUpdateData(TObject *Sender, TCustomClientDataSet 

*DataSet) 

{ 

DataSet->FieldByName ( "EMPNO" ) ->ProviderFlags .Clear ( ) ; 
DataSet->FieldByNarae ("EMPNO" )->ProviderFlags « pflnWHere « pflnKey; 
DataSet->FieldByName ( "TITLE" ) ->ProviderFlags .Clear ( ) ; 
DataSet->FieldByName ("TITLE" )->ProviderFlags « pflnUpdate; 
DataSet->FieldByName ( "DEPT" ) ->ProviderFlags .Clear ( ) ; 
DataSet->FieldByName("DEPT")->ProviderFlags « pflnWhere; 

} 

E possibile usare la proprieta UpdateFlags per influenzare il modo in cui vengono 
applicati gli aggiornamenti anche si sta aggiomando un dataset senza usare 
istruzioni SQL generate dinamicamente. Anche questi flag determinano quali campi 
vengono usati per individuare i record e quali campi vengono aggiornati. 

Vaglio dei singoli aggiornamenti 



Immediatamente prima che ciascun aggiornamento venga applicato, il provider di 
dataset riceve un evento BeforellpdateRecord. Questo evento puo essere usato per 
modificare i record prima vengano applicati, analogamente a come si usa l'evento 
OnUpdateData per modificare interi pacchetti delta. Ad esempio, il provider non 
confronta i campi BLOB (come i memo) quando esegue il controllo su conflitti di 
aggiornamento. Se si vogliono controllare eventuali errori di aggiornamento relativi 
a campi BLOB, e possibile utilizzare l'evento BeforellpdateRecord. 
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Inoltre, si puo usare questo evento per applicare personalmente gli aggiornamenti o 
per vagliare e rigettare gli aggiornamenti. II gestore dell'evento BeforellpdateRecord 
permette di segnalare che un aggiornamento e gia stato gestito e non deve essere 
applicato. II provider quindi salta quel record, ma non lo considera come un errore di 
aggiornamento. Per esempio, questo evento fornisce a una procedura memorizzata 
(che non puo essere aggiornata automaticamente) un meccanismo per applicare gli 
aggiornamenti, consentendo al provider di saltare qualsiasi elaborazione automatica 
dal momento che il record viene aggiornato dall'interno del gestore di evento. 

Risoluzione degli errori di aggiornamento sul provider 



Quando si determina una condizione di errore non appena il provider di dataset 
tenta di inviare un record nel pacchetto delta, si verifica un evento OnllpdateError. Se 
il provider non riesce a risolvere un errore di aggiornamento, memorizza 
temporaneamente una copia del record che ha generato l'errore. Completata 
l'elaborazione del record, il provider restituisce il numero di errori incontrati e copia 
i record non risolti in un pacchetto dati risultato che viene ripassato al client per 
un'ulteriore riconciliazione. 

Nelle applicazioni multi-tiered, questo meccanismo permette di gestire qualsiasi 
errore di aggiornamento che e possibile risolvere automaticamente sull'application 
server, pur consentendo ancora l'interazione con l'utente sull'applicazione client per 
correggere le condizioni di errore. 

II gestore OnllpdateError riceve una copia del record che non puo essere modificato, 
un codice di errore dal database e un'indicazione del fatto che il resolver stesse 
cercando di inserire, cancellare o aggiornare il record. II record problematico viene 
restituito in un dataset client. Su questo dataset non si devono mai usare i metodi per 
lo spostamento tra i dati. Tuttavia, per ciascun campo del dataset, e possibile usare le 
proprieta NewValue, OldValue e CurValue per determinare la causa del problema e 
apportare tutte le modifiche necessarie per risolvere l'errore di aggiornamento. Se il 
gestore di evento OnllpdateError puo correggere il problema, imposta il parametro 
Response in modo che venga applicato il record corretto. 

Applicazione di aggiornamenti a dataset che non rappresentano una 
singola tabella 



Quando un provider di dataset genera istruzioni SQL che applicano gli 
aggiornamenti direttamente su un server di database, e necessario f ornire il nome 
della tabella di database che contiene i record. Questo compito puo essere gestito in 
modo automatico per molti dataset, come i dataset di tipo tabella o i componenti 
TQuery aggiornati in diretta. Gli aggiornamenti automatici, tuttavia, rappresentano 
un problema nel caso il provider debba applicare gli aggiornamenti ai dati sottostanti 
una procedura registrata a partire da un set risultato o da una query su piu tabelle. 
Non esiste un modo semplice per accertare il nome della tabella a cui dovrebbero 
essere applicati gli aggiornamenti. 

Se la query o la procedura registrata e un dataset BDE (TQuery o TStoredProc) a cui e 
associato un oggetto update, il provider utilizzera l'oggetto update. Tuttavia, se non 
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esiste un oggetto update, e possibile fornire da programma il nome della tabella in un 
gestore di evento OnGetTableName. Una volta che il gestore di evento ha fornito il 
nome della tabella, il provider e in grado di generare le opportune istruzioni SQL per 
applicare gli aggiornamenti. 

II passaggio del nome della tabella funziona solamente se il destinatario degli 
aggiornamenti e una singola tabella di database (vale a dire, e necessario aggiornare 
solo i record di una tabella). Se gli aggiornamenti devono apportare modifiche a piu 
tabelle di database sottostanti, e necessario applicare gli aggiornamenti in modo 
esplicito nel codice utilizzando l'evento BeforellpdateRecord del provider. Dopo che il 
gestore di evento ha applicato un aggiornamento, si deve impostare a true il 
parametro Applied del gestore di evento in modo che il provider non generi un errore. 

Se il provider e associato a un dataset BDE, e possibile utilizzare nel gestore di evento 
BeforellpdateRecord un oggetto update per applicare gli aggiornamenti mediante 
istruzioni SQL personalizzate. Per i dettagli, consultare "Aggiornamento di dataset 
mediante oggetti update" a pagina 24-41 for details. 

Risposta agli eventi generati dal client 



I componenti provider implementano un evento di tipo generico che permette di 
creare proprie chiamate dai dataset client direttamente al provider. Si tratta 
dell'evento OnDataRequest. 

OnDataRequest non fa parte del normale funzionamento del provider. E solo un 
aggancio per consentire ai dataset client di comunicare direttamente con i provider. II 
gestore di evento accetta come parametro in ingresso un Ole Variant e restituisce un 
Ole Variant. Usando gli Ole Variant, l'interfaccia e sufficientemente generica per 
contenere quasi tutte le informazioni che si vogliono passare al o dal provider. 

Per generare un evento OnDataRequest, l'applicazione client chiama direttamente il 
metodo DataRequest del dataset client. 

Gestione dei vincoli del server 



La maggior parte dei sistemi di gestione dei database relazionali implementa vincoli 
sulle tabelle per far rispettare l'integrita dei dati. Un vincolo e una regola che governa 
i valori dei dati nelle tabelle e nelle colonne, o le relazioni tra i dati tra le colonne di 
tabelle differenti. Per esempio, la maggior parte dei database relazionali conformi a 
SQL-92 supporta i seguenti vincoli: 

• NOT NULL, per garantire che un valore fornito a una colonna abbia un valore. 

• NOT NULL UNIQUE, per garantire che il valore della colonna abbia un valore e 
non duplichi un altro valore presente in quella colonna per un altro record. 

• CHECK, per garantire che un valore fornito a una colonna cada all'interno di un 
determinato intervallo, o appartenga a un insieme finito di possibili valori. 
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• CONSTRAINT, un vincolo di controllo a livello di tabella che si applica a piu 
colonne. 

• PRIMARY KEY, per designare una o piu colonne come chiave principale della 
tabella per l'indicizzazione. 

• FOREIGN KEY, per designare una o piu colonne di una tabella che fanno 
riferimento a un'altra tabella. 

Questo elenco non e esclusivo. II server di database puo supportare alcuni o tutti 
questi vincoli, in parte o completamente, nonche ulteriori vincoli. Per ulteriori 
informazioni sui vincoli supportati, consultare la documentazione del server. 

I vincoli del database server duplicano ovviamente molti tipi di controlli sui dati 
normalmente gestiti dalle tradizionali applicazioni database desktop. Nelle 
applicazioni database multi-tier e possibile sfruttare i vantaggi dei vincoli del server 
Se il provider opera con un dataset BDE, la proprieta Constraints consente di replicare 
e applicare i vincoli del server ai dati passati e ricevuti dai dataset client. Se 
Constraints e true (impostazione predefinita), i vincoli del server memorizzati nel 
dataset sorgente vengono inclusi nei pacchetti dati e hanno effetto sui tentativi del 
client di aggiornare i dati. 

Prima che il provider server possa trasferire ai dataset client le informazioni sui 
vincoli, deve recuperare i vincoli dal server di database. Per ottenere dal server i 
vincoli sui database, utilizzare SQL Explorer per importare nel Data Dictionary i 
vincoli del server di database e le espressioni predefinite. I vincoli e le espressioni 
predefinite inclusi nel Data Dictionary sono resi automaticamente disponibili ai 
dataset BDE. 

A volte si potrebbe non voler applicare i vincoli del server ai dati inviati a un dataset 
client. Per esempio, un dataset client che riceve dati in pacchetti e consente 
l'aggiornamento in locale dei record prima di prelevare altri record, potrebbe aver 
bisogno di disattivare alcuni vincoli del server che potrebbero essere attivati per la 
presenza di un set di dati momentaneamente incompleto. Per impedire la replica dei 
vincoli dal provider al dataset client, impostare Constraints a false. Si noti, inoltre, che 
i dataset client possono disattivare e attivare i vincoli usando i metodi 
DisableConstraints e EnableConstraints. Per ulteriori informazioni sull'attivazione e 
sulla disattivazione dei vincoli da parte del dataset client, consultare "Gestione dei 
vincoli dal server" a pagina 27-32. 
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Capitolo 




Creazione di applicazioni multi-tier 

Questo capitolo descrive come creare un'applicazione database multi-tier client/ 
server. Un'applicazione multi-tier client /server e partizionata in unita logiche che 
vengono eseguite insieme su macchine distinte. Le applicazioni multi-tier 
condividono i dati e comunicano con le altre applicazioni in una rete locale o anche 
su Internet. Esse forniscono molti vantaggi, come la logica di gestione centralizzata e 
le applicazioni thin client. 

Nella sua forma piu semplice, detta anche "modello three-tier", un'applicazione 
multi-tier e suddivisa in tre parti: 

• Applicazione client: fornisce un'interfaccia utente nella macchina dell'utente 
stesso. 

• Application server: risiede in una postazione centrale della rete accessibile a tutti i 
client e fornisce servizi comuni per i dati. 

• Server di database remoto: fornisce il sistema relazionale di gestione del database 
(RDBMS) 

In questo modello three-tier l'application server gestisce il flusso dei dati tra i client e 
il database server remoto, percio a volte viene chiamato "data broker". Solitamente si 
creano solo l'application server e i suoi client, ma, volendo, si pud anche creare un 
database di back end personalizzato. 

Nelle applicazioni multi-tier piu complesse i servizi aggiuntivi risiedono tra un client 
e un database server remoto. Per esempio, potrebbero esservi un broker di servizi di 
sicurezza per gestire in modo sicuro le transazioni Internet, o dei servizi di bridge per 
gestire la condivisione dei dati con database su altre piattaforme. 

II supporto della VCL e della CLX per lo sviluppo di applicazioni multi-tier e un 
ampliamento del modo in cui i dataset client comunicano con un componente 
provider utilizzando pacchetti dati trasportabili. In questo capitolo viene 
specificatamente descritta la creazione di un'applicazione database three-tier. Dopo 
aver capito come creare e gestire un'applicazione three-tier, si puo passare a creare e 
ad aggiungere ulteriori livelli di servizi, a seconda delle necessita. 
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Vantaggi di un modello database multi-tier 



II modello database multi-tier suddivide un'applicazione database in parti logiche. 
L'applicazione client pud occuparsi della visualizzazione dei dati e delle interazioni 
con l'utente. Teoricamente, l'applicazione non sa nulla del modo in cui vengono 
memorizzati o conservati i dati. L'application server (il tier intermedio) coordina ed 
elabora le richieste e gli aggiornamenti da parte di piu client. Gestisce, inoltre, tutti i 
dettagli della definizione dei dataset e dell'interazione con il server di database. 

I vantaggi di questo modello multi-tier comprendono: 

• Incapsulamento della logica di gestione in un tier intermedio condiviso. 

Applicazioni client differenti accedono tutte alle stesso tier intermedio. Cio 
consente di evitare la ridondanza (e i costi di manutenzione) della duplicazione 
delle regole di gestione per ogni singola applicazione client. 

• Applicazioni thin client. Le applicazioni client possono essere scritte in modo da 
occupare poco spazio, delegando la maggior parte dell'elaborazione ai tier 
intermedi. Non solo si hanno applicazioni client piu piccole, ma anche piu facili da 
distribuire, in quanto non e necessario preoccuparsi della loro installazione, 
configurazione e della manutenzione del software per la connettivita al database 
(come con Borland Database Engine e con i server di database lato client). Le 
applicazioni thin client possono anche essere distribuite su Internet per una 
maggior flessibilita. 

• Elaborazione distribuita dei dati. Distribuendo il lavoro di un'applicazione su 
piu macchine, e possibile migliorare le prestazioni grazie al bilanciamento del 
carico, e consentire ai sistemi ridondanti di subentrare quando un server si blocca. 

• Maggiori possibility di sicurezza. E possibile isolare le funzioni riservate e 
delicate in tier che hanno restrizioni di accesso differenti. Cio fornisce livelli 
flessibili e configurabili di sicurezza. I tier intermedi possono limitare i punti di 
accesso al materiale riservato, consentendo di controllare piu facilmente l'accesso. 
Se si usa HTTP o COM+, si possono sfruttare i vantaggi dei modelli di sicurezza 
che tali tecnologie supportano. 

Applicazioni multi-tier basate su provider 



Le applicazioni multi-tier si basano sull'uso dei componenti delle pagine DataSnap, 
Data Access e possibilmente WebServices della Component palette, oltre a un 
modulo dati remoto che viene creato da un wizard presente sulla pagina Multitier o 
WebServices della finestra di dialogo New Items. Essi si basano sulla capacita dei 
componenti provider di assemblare dati in pacchetti dati trasportabili e di gestire gli 
aggiornamenti ricevuti come pacchetti delta trasportabili. 
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I componenti necessari per un'applicazione multi-tier sono descritti nella Tabella 
29.1: 



Tabella 29.1 Componenti usati nelle applicazioni multi-tier 



Componente 

Moduli dati remoti 



Componente 
Provider 

Componente 
dataset Client 



Componenti 
connection 



Descrizione 

Moduli dati specialistici che operano con Automation server COM e con 
un'applicazione Web Service per fornire 1'accesso delle applicazioni client a 
tutti i provider che contengono. Vengono usati negli application server. 

Un broker di dati che fornisce i dati tramite la creazione di pacchetti dati e 
risolve gli aggiornamenti del client. Viene usato negli application server. 

Un dataset specializzato che usa midas.dll per gestire i dati memorizzati 
nei pacchetti dati. II dataset client e utilizzato nell'applicazione client. 
Memorizza gli aggiornamenti nella cache locale e li applica in pacchetti 
delta all'application server. 

Una famiglia di componenti che individua il server, le connessioni della 
scheda e rende disponibile ai dataset client 1'interfaccia IAppServer. Ogni 
componente connection e specializzato per usare un particolare protocollo 
di comunicazione. 



II provider e i componenti dataset client necessitano di midas.dll o midaslib.dcu, che 
gestisce i dataset memorizzati come pacchetti dati. (Notare che, poiche il provider e 
utilizzato sull'application server e il dataset client e utilizzato sull'applicazione client, 
se si utilizza midas.dll, e necessario distribuirla sia sull'application server che 
sull'applicazione client.) 

Se si utilizzano dataset BDE, l'application server potrebbe richiedere anche l'uso di 
SQL Explorer per agevolare l'amministrazione del database e per importare nel Data 
Dictionary i vincoli del server, in modo da poterli controllare a qualsiasi livello 
dell'applicazione multi-tier. 

Per distribuire l'application server e necessario acquistare le licenze per il server. 

Una panoramica dell'architettura in cui sono inseriti questi componenti e presentata 
in "Utilizzo di un'architettura multi-tier" a pagina 18-13. 

Panoramica di un'applicazione three-tier 



Le seguenti fasi illustrano una normale sequenza di eventi per un'applicazione three- 
tier basata su provider: 

1 Un utente avvia l'applicazione client. II client si collega all'application server (che 
puo essere specificato in fase di progettazione o di esecuzione). Se l'application 
server non e gia in esecuzione, viene avviato. II client riceve un'interfaccia 
IAppServer per la comunicazione con l'application server. 

2 II client richiede dati dall'application server. Un client puo richiedere i dati in 
un'unica soluzione o pochi per la volta per tutta la sessione (prelievo su richiesta). 

3 L'application server recupera i dati (stabilendo innanzi tutto, se necessario, una 
connessione al database), crea i pacchetti dati per il client e li restituisce al client. 
Altre informazioni, (ad esempio, le caratteristiche di visalizzazione dei campi) 
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possono essere incluse nei metadati del pacchetto dati. Questo processo di 
inglobamento dei dati in pacchetti viene chiamato "fomitura". 

4 II client decodifica il pacchetto dati e visualizza i dati all'utente. 

5 Man mano che l'utente interagisce con l'applicazione client, i dati vengono 
aggiornati (vengono aggiunti, cancellati o modificati record). Queste modifiche 
vengono memorizzate in un registro delle modifiche dal client. 

6 Infine il client applica i suoi aggiornamenti all'application server, normalmente in 
risposta a un'azione dell'utente. Per applicare questi aggiornamenti, il client 
compone in un pacchetto il suo registro delle modifiche e lo invia come un 
pacchetto dati al server. 

7 L'application server decodifica il pacchetto dati e invia gli aggiornamenti (se e il 
caso, nel contesto di una transazione). Se un record non puo essere inviato al 
server (per esempio, perche un'altra applicazione ha modificato il record, dopo 
che il record era stato richiesto da un client e prima che quest'ultimo applicasse i 
suoi aggiornamenti), l'application server tenta di riconciliare le modifiche del 
client con i dati correnti, oppure salva i record che potrebbero non essere inoltrati. 
Questo processo di invio dei record e di memorizzazione nella cache dei record 
problematici viene chiamato "risoluzione". 

8 Quando l'application server termina il processo di risoluzione, restituisce tutti i 
record non inoltrati al client per un'ulteriore risoluzione. 

9 II client riconcilia i record non risolti. Esistono molti modi in cui un client puo 
riconciliare i record non risolti. Normalmente, il client cerca di correggere la 
situazione che impedisce ai record di essere inviati o scarta le modifiche. Se la 
situazione di errore puo essere rettificata, il client applica di nuovo gli 
aggiornamenti. 

10 II client effettua l'aggiomamento dei suoi dati dal server. 

Struttura dell'applicazione client 



Per l'utente finale l'applicazione client di un'applicazione multi-tier appare e si 
comporta in modo non diverso da una tradizionale applicazione two-tier che utilizza 
aggiornamenti in cache. L'interazione con l'utente ha luogo tramite i controlli 
standard associati ai dati, che visualizzano i dati da un componente TClientDataSet. 
Per informazioni dettagliate sull'uso delle proprieta, degli eventi e dei metodi dei 
dataset client, consultare il Capitolo 27, "Utilizzo dei dataset client". 

TClientDataSet preleva i dati da un componente provider e vi applica gli 
aggiornamenti, esattamente come nelle applicazioni two-tier che utilizzano un 
dataset client con un provider esterno. Per i dettagli sui componenti provider, vedere 
il Capitolo 28, "Uso di componenti provider". Per i dettagli sulle funzioni dei dataset 
client che ne agevolano la comunicazione con un provider, vedere "Uso di un dataset 
client con un provider di dati" a pagina 27-26 

II dataset client comunica con il provider attraverso l'interfaccia IAppServer. Esso 
ottiene questa interfaccia da un componente connection. II componente connection 
stabilisce la connessione all'application server. Sono disponibili differenti 
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componenti connection per usare protocolli di comunicazione diversi. Questi 
componenti connection sono riassunti nella seguente tabella: 



Tabella 29.2 Componenti connection 



Componente 


Protocollo 




TDCOMConnection 


DCOM 




TSocketConnection 


Windows sockets 


(TCP/IP) 


TWebCormection 


HTTP 




TSOAPConnection 


SOAP (HTTP and 


XML) 



La pagina DataSnap della Component palette include anche un componente 
connection che non si collega affatto a un application server, ma fornisce invece 
un'interfaccia IAppServer che deve essere utilizzata dai dataset client durante la 
comunicazione con provider presenti nella stessa applicazione. Questo componente, 
TLocalConnection, non e necessario, ma semplifica un successivo ampliamento a 
multi-tier dell'applicazione. 

Per ulteriori informazioni sull'uso dei componenti connection, consultare 
"Connessione all'application server" a pagina 29-24. 

La struttura dell'application server 



Quando un application server viene impostato ed eseguito, non stabilisce alcuna 
connessione con le applicazioni client. Sono invece le applicazioni client che iniziano 
e mantengono la connessione. Un'applicazione client usa un componente connection 
per stabilire una connessione con l'application server e utilizza l'interfaccia 
dell'application server per comunicare con un provider selezionato. Tutto cio 
avviene automaticamente, senza che si debba scrivere del codice per gestire le 
richieste in arrivo o fornire le interfacce. 

La base di un application server e un modulo dati remoto, che e un modulo dati 
specializzato che supporta l'interfaccia IAppServer (per gli application server che 
funzionano anche come Web Service, il modulo dati remoto supporta anche 
l'interfaccia IAppServerSOAP e la preferisce a IAppServer.) Le applicazioni client 
utilizzano l'interfaccia del modulo dati remoto per comunicare con i provider 
sull'application server. Quando il modulo dati remoto usa IAppServerSOAP, il 
componente connection lo adatta a un'interfaccia di IAppServer che i dataset client 
sono in grado di utilizzare. 

Esistono due tipi di moduli dati remoto: 

• I moduli dati remoti basati su COM sono moduli dati che utilizzano un oggetto 
associate detto oggetto di implementazione, che deriva da 

REMOTEDATAMODULE_IMPL(). REMOTEDATAMODULEJMPL e una macro 
definita in Atlvcl.h che elenca gli antenati dell'oggetto di implementazione. Questi 
includono le classi CComObjectRootEx e CComCoClass di ATL, oltre che l'interfaccia 
IAppServer. Se si sta creando un application server che sia in grado di sfruttare i 
servizi distribuiti per le applicazioni forniti da MTS o COM+, 
REMOTEDATAMODULEJMPL include inoltre l'interfaccia IObjectControl, 
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necessaria per tutti gli oggetti transazionali. La classe di implementazione, 
generata automaticamente da un wizard, ha accesso a un'interfaccia 
IObjectContext, messa a disposizione dal sistema per suo conto, e che viene 
utilizzata dall'interfaccia per gestire transazioni, liberare risosrse o sfruttare il 
supporto per la sicurezza. 

• I moduli dati SOAP sono moduli dati che implementano l'interfaccia 
IAppServerSOAP come interfaccia richiamabile. Questi moduli dati vengono 
aggiunti a un'applicazione Web Service e consentono ai client di accedere ai dati 
come un Web Service. Per informazioni sulle applicazioni Web Service, vedere il 
Capitolo 36, "Utilizzo dei Web Services". 

Se l'application server deve essere distribuito in ambiente MTS o COM+, il modulo 
dati remoto include degli eventi legati all'attivazione o alia disattivazione 
dell'application server. Cio consente all'application server di acquisire le connessioni 
ai database al momento della sua attivazione e di rilasciarle quando viene disattivato. 

Contenuti del modulo dati remoto 

Come con qualsiasi altro modulo dati, nel modulo dati remoto e possibile includere 
qualsiasi componente non visuale. Vi sono tuttavia alcuni componenti che e 
necessario includere: 

• Se il modulo dati remoto espone le informazioni provenienti da un server di 
database, deve includere un componente dataset per rappresentare i record da 
quel server di database. Possono essere necessari altri componenti, come un 
componente database connection di qualsiasi tipo, per permettere al dataset di 
interagire con un server di database. Per informazioni sui dataset, consultare il 
Capitolo 22, "I dataset". Per informazioni sui componenti database connection, 
veder il Capitolo 21, "Connessione ai database". 

Per ogni dataset che il modulo dati remoto espone ai client, deve includere un 
provider di dataset. Un provider di dataset assembla i dati in pacchetti dati che 
vengono inviati ai dataset client e applica aggiornamenti ricevuti dai dataset client 
a un dataset sorgente o a un server di database. Per ulteriori informazioni sui 
provider di dataset, vedere il Capitolo 28, "Uso di componenti provider". 

• Per ogni documento XML che il modulo dati remoto espone ai client, deve 
includere un provider XML. Un provider XML agisce come un provider di dataset, 
salvo che preleva i dati da un documento XML invece che da un server di database 
e vi applica aggiornamenti. Per ulteriori informazioni sull'utilizzo di provider 
XML, consultare "Impiego di un documento XML come origine di un provider" a 
pagina 30-8. 

Non confondere un componente per la connessione ai database, che connette i 
dataset a un server di database, con il componente connection usato dalle 
applicazioni client nelle applicazioni multi-tier. I componenti connection per le 
applicazioni multi-tier sono inclusi sulle pagine DataSnap o WebServices della 
Component palette. 



29-6 Guida alia programmazione 



Applicazioni multi-tier basate su provider 

Uso di moduli dati transazionali 

E possibile scrivere application server in grado di sfruttare i servizi speciali per le 
applicazioni distribuite messi a disposizione da MTS (prima di Windows 2000) o da 
COM+ (in ambiente Windows 2000 e successivi). Per fare cio, invece di un comune 
modulo dati remoto, si crea un modulo dati transazionale. 

Quando si usa un modulo dati a transazionale, l'applicazione pud sfruttare i seguenti 
servizi speciali: 

• Sicurezza. MTS e COM+ forniscono all'application server un servizio per la 
sicurezza basato sui ruoli. Ai client vengono assegnati dei ruoli che determinano 
se essi possono accedere o meno all'interfaccia dell'application server. Per 
accedere a questi servizi di sicurezza, e possibile utilizzare l'interfaccia 
IObjectContext a cui si accede mediante la classe di implementazione. Per ulteriori 
informazioni sulla sicurezza MTS e COM+, consultare il paragrafo "Sicurezza 
basata sul ruolo" a pagina 44-17. 

• Condivisione degli handle del database. I moduli dati transazionali condividono 
automaticamente le connessioni al database effettuate tramite ADO o (se si sta 
utilizzando MTS e si attiva MTS POOLING) BDE. Quando un client ha completato 
una connessione al database, un altro client pud riutilizzarla. Questa tecnica riduce 
il traffico di rete, in quanto il tier intermedio non ha bisogno di sconnettersi dal 
database server remoto e di registrarsi poi di nuovo. Quando si condividono gli 
handle del database, il componente di conessione al database deve impostare la 
sua proprieta KeepConnection a false, in modo che l'applicazione consenta la 
massima condivisione delle connessioni. Per ulteriori informazioni sulla 
centralizzazione per la gestione del database, consultare "Distributori di risorse di 
database" a pagina 44-6. 

• Transazioni. Quando si utilizza un modulo dati transazionale, e possibile fornire 
un supporto per le transazioni ancora piu evoluto di quello disponibile con una 
singola connessione database. I moduli dati transazionali possono partecipare a 
transazioni che coinvolgono piu database, o includere funzioni che non 
coinvolgono affatto i database. Per ulteriori informazioni sul supporto 
transazionale fornito dagli oggetti transazionali, come i moduli dati transazionali, 
consultare "Gestione delle transazioni nelle applicazioni multi-tiered" a 
pagina 29-18. 

• Attivazione just-in-time e disattivazione as-soon-as-possible. E possibile 
scrivere il proprio server in modo che le istanze vengano attivate e disattivate 
quando e necessario.Quando si usa l'attivazione just-in-time e la disattivazione as- 
soon-as-possible, l'application server viene istanziato solo quando e necessario 
gestire le richieste del client. Cio impedisce di bloccare le risorse come gli handle 
del database quando non vengono usati. 

L'uso dell'attivazione just-in-time e della disattivazione as-soon-as-possible 
fornisce una soluzione intermedia tra il routing di tutti i client tramite una singola 
istanza del modulo dati remoto e la creazione di un'istanza distinta per ogni 
connessione del client. Con un'unica istanza l'application server deve gestire tutte 
le chiamate al database tramite una singola connessione al database. Cio agisce 
come un collo di bottiglia, e puo avere effetti sulle prestazioni quando ci sono 
molti client. Con piu istanze del modulo dati remoto, ciascuna istanza puo 
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mantenere una distinta connessione al database, evitando pertanto la necessita di 
serializzare l'accesso al database. Tuttavia, cio monopolizza le risorse perche gli 
altri client non possono usare la connessione al database mentre e associata al 
modulo dati remoto di un altro client. 

Per sfruttare i vantaggi delle transazioni, dell'attivazione just-in-time e della 
disattivazione as-soon-as-possible, le istanze del modulo dati remoto devono essere 
senza stato. Cio significa che occorre fornire un supporto ulteriore nel caso in cui il 
client si appoggi alle informazioni di stato. Per esempio, durante l'esecuzione di un 
recupero dati incrementale, il client deve passare le informazioni relative al record 
corrente. Cio significa che occorre fornire un supporto ulteriore nel caso in cui il 
client si appoggi alle informazioni di stato. Per maggiori informazioni sulle 
informazioni di stato e sui moduli dati remoto nelle applicazioni multi-tier, 
consultare la sezione "Supporto delle informazioni di stato nei moduli dati remoti" a 
pagina 29-20. 

Per impostazione predefinita, tutte le chiamate generate automaticamente a un 
modulo dati sono transazionali (cioe , partono dal presupposto che, al termine della 
chiamata, sia possibile disattivare il modulo dati e confermare o annullare tutte le 
transazioni attive). E possibile scrivere un modulo dati transazionale, che dipende 
dalle informazioni di stato persistenti, impostando a false la proprieta AutoComplete 
per l'attivazione just-in-time, anche se non supportera le transazioni, o per la 
disattivazione as-soon-as-possible a meno che non si usi un'interfaccia custom. 

Gli application server contenenti moduli dati transazionali non dovrebbero aprire le 
connessioni ai database finche non viene attivato il modulo dati. In fase di 
progettazione bisogna accertarsi che tutti i dataset non siano attivi e che il database 
non sia collegato prima di eseguire l'applicazione. Nell'applicazione stessa 
aggiungere il codice, per aprire le connessioni al database quando il modulo dati 
viene attivato, e chiuderlo quando viene disattivato. 

Centralizzazione di moduli dati remoti 

La centralizzazione di oggetti consente di creare una cache di application server che 
vengono condivisi dai rispettivi client, risparmiando in tal modo risorse. La modalita 
di funzionamento dipende dal tipo di modulo dati remoto e dal protocollo di 
connessione. 

Se si sta creando un modulo dati transazionale che verra installato in ambiente 
COM+, e possibile usare il COM+ Component Manager per installare l'application 
server come oggetto centralizzato. Per maggiori informazioni, consultare 
"Condivisione degli oggetti" a pagina 44-10. 

Anche se non si sta utilizzando un modulo dati transazionale, si pud trarre vantaggio 
dalla centralizzazione degli oggetti se la connessione viene stabilita mediante il 
protocollo TWebConnection. In questo secondo tipo di centralizzazione di oggetti, si 
limita il numero di istanze che vengono create dell'application server. In questo 
modo si limita il numero di connessioni database che e necessario conservare, oltre a 
tutte le altre risorse utilizzate dall'application server. 

Quando l'applicazione Web Server (che passa le chiamate all'application server) 
riceve richieste dal client, le passa al primo application server disponibile nel sistema 
centralizzato. Se non c'e un application server, disponibile, ne crea uno nuovo (fino al 



29-8 Guida alia programmazione 



Applicazioni multi-tier basate su provider 

numero massimo specif icato). In questo modo si fornisce una via di mezzo tra 
l'indirizzamento di tutti i client su una singola istanza dell'application server (che 
puo comportarsi da collo di bottiglia), e la creazione di un'istanza separata per ogni 
connessione client (che puo richiedere molte risorse). 

Se un'istanza dell'application server nel sistema centralizzato non riceve nessuna 
richiesta dai client per un certo periodo di tempo, viene automaticamente resa 
disponibile. In questo si impedisce al sistema centralizzato di monopolizzare risorse 
a meno che non siano utilizzate. 

Per impostare la centralizzazione degli oggetti utilizzando una connessione Web 
(HTTP), fare quanto segue: 

1 Individuare il metodo UpdateRegistry della classe di implementazione. Questo 
metodo appare nel file header della unit di implementazione: 

static HRESULT WINAPI UpdateRegistry (BOOL bRegister) 
{ 

TRemoteDataModuleRegistrar regObj (GetObjectCLSlD( ) , GetProglDf), GetDescriptionO); 
return regObj .UpdateRegistry (bRegister) ; 

} 

2 Impostare a true il flag Register Pooled della variabile regObj, che e un'istanza di 
TRemoteDataModideRegistrar. Potrebbe essere necessario impostare inoltre altre 
proprieta di regObj per indicare in che modo dovra essere gestita la cache dei 
moduli dati remoti. Ad esempio, il codice seguente consente un massimo di 10 
istanze del modulo dati remoto e le elimina dalla cache nel caso in cui rimangano 
inutilizzate per piu di 15 minuti: 

static HRESULT WINAPI UpdateRegistry (BOOL bRegister) 
{ 

TRemoteDataModuleRegistrar regObj (GetObjectCLSlDO , GetProglDf), GetDescriptionO); 
regObj .RegisterPooled = true; 
regObj .Timeout = 15; 
regObj .Max = 10; 

return regObj .UpdateRegistry (bRegister) ; 

} 

Quando si utilizza l'uno o l'altro di questi metodi per la centralizzazione degli 
oggetti, e necessario che l'application server sia senza stato. Cio perche una singola 
istanza e in grado di gestire potenzialmente richieste provenienti da parecchi clients. 
Se facesse affidamendo alia persistenza delle informazioni di stato, i client 
potrebbero interferire fra di loro. Per maggiori informazioni su come garantire che il 
modulo dati remoti sia senza stato, consultare la sezione "Supporto delle 
informazioni di stato nei moduli dati remoti" a pagina 29-20. 

Scelta di un protocollo di connessione 



Ogni protocollo di comunicazione che puo essere usato per collegare le applicazioni 
client all' application server fornisce specifici vantaggi. Prima di scegliere un 
protocollo, si deve considerare il numero di client attesi, come verra distribuita 
l'applicazione e i piani di sviluppo futuri. 
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Uso di connessioni DCOM 

DCOM fomisce l'approccio piu diretto alia comunicazione, in quanto non richiede 
ulteriori applicazioni di runtime sul server. Tuttavia, poiche DCOM non e incluso in 
Windows 95, le macchine client meno recenti potrebbero non averlo installato. 

DCOM fornisce l'unico approccio che permette di usare i servizi di sicurezza quando 
si scrive un modulo dati transazionale. Questi servizi di sicurezza si basano 
sull'assegnazione di ruoli ai chiamanti degli oggetti transazionali. Quando si utilizza 
DCOM, DCOM identifica il chiamante come il sistema che effettua la chiamata 
all'application server (MTS o COM+). Pertanto, e possibile determinare in modo 
preciso il ruolo del chiamante. Quando si usano altri protocolli, tuttavia, c'e un 
eseguibile di runtime, diverso dall'application server, che riceve le chiamate del 
client. Questo eseguibile di runtime effettua le chiamate COM nell'application server 
per conto del client. A causa di cio, e impossibile assegnare ruoli ai diversi clients: 
l'eseguibile di runtime risulta, in effetti, l'unico client. Per ulteriori informazioni sulla 
sicurezza e sugli oggetti transazionali, consultare il paragrafo "Sicurezza basata sul 
ruolo" a pagina 44-17. 

Uso delle connessioni socket 

I socket TCP/IP permettono di creare client leggeri. Per esempio, se si stanno 
scrivendo applicazioni client per Web, non si pud essere certi che i sistemi client 
supportino DCOM. I socket forniscono un minimo comune denominatore che sara 
disponibile per la connessione all'application server. Per ulteriori informazioni sui 
socket, consultare il Capitolo 37, "Operazioni con i socket". 

Anziche istanziare il modulo dati remoto direttamente dal client (come succede con 
DCOM), i socket usano una distinta applicazione sul server (ScktSrvr.exe), che 
accetta le richieste del client e istanzia l'application server usando COM. II 
componente connection sul client e ScktSrvr.exe sul server sono responsabili dello 
smistamento delle IAppServer. 

ScktSrvr.exe puo essere eseguito come un' applicazione di servizio di NT. Per 
registrarlo come tale con Service manager, lo si deve avviare usando sulla riga 
comandi l'opzione -install. Per annullarne la registrazione, lo si deve awiare 
utilizzando sulla riga comandi l'opzione -uninstall. 

Prima che si possa utilizzare una connessione socket, l'application server deve 
comunicare la sua disponibilita ai client utilizzando una connessione socket. Per 
impostazione predefinita, tutti i nuovi moduli dati remoti si registrano 
automaticamente mediante l'oggetto TRemoteDataModuleRegistrar nel metodo 
UpdateRegistry dell'oggetto di implementazione. E possibile impedire questa 
registrazione impostando a false la proprieta EnableSocket dell'oggetto. 

Poiche i precedenti server non aggiungevano questa registrazione, e possibile 
disattivare il controllo sulla registrazione di un application server deselezionando la 
voce di menu Connections I Registered Objects Only di ScktSrvr.exe. 

Quando si usano i socket, sul server non c'e alcuna protezione contro i guasti dei 
sistemi client prima che rilascino un riferimento alle interfacce sull'application 
server. Anche se si ha un minor traffico rispetto all'uso di DCOM (che in via messaggi 
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periodici per il mantenimento in attivita ), cio puo portare a un application server che 
non e in grado di rilasciare le sue risorse perche non sa che il client e spento. 

Uso di connessioni 

HTTP permette di creare client che possono comunicare con un application server 
protetto da un firewall. I messaggi HTTP forniscono un accesso controllato alle 
applicazioni interne, consentendo cosi una distribuzione estesa e in tutta sicurezza 
delle proprie applicazioni client. Analogamente alle connessioni socket, i messaggi 
HTTP forniscono un minimo comune denominatore che sara disponibile per 
connettersi all'application server. Per maggiori informazioni su messaggi HTTP, 
consultare il Capitolo 32, "Creazione di applicazioni server per Internet". 

Invece di istanziare direttamente il modulo dati remoto dal client (come accade con 
DCOM), le connessioni basate su HTTP utilizzano un'applicazione Web server sul 
server (httpsrvr.dll) che accetta le richieste dei client e istanzia l'application server 
utilizzando COM. Per questo motivo, sono chiamate anche connessioni Web. II 
componente connessione sul client e httpsrvr.dll sul server sono responsabili del 
marshaling delle chiamate a IAppServer. 

Le connessioni Web possono sfruttare la sicurezza SSL fornita da wininet.dll (una 
libreria di utilita per Internet che viene eseguita sul sistema client). Una volta 
configurato il server web sul sistema server in modo che richieda l'autenticazione, e 
possibile specificare il nome dell'utente e la password utilizzando le proprieta del 
componente connessione Web. 

Come ulteriore misura di sicurezza, l'application server deve notificare la sua 
disponibilita ai client utilizzando una connessione Web. Per impostazione 
predefinita, tutti i nuovi moduli dati remoti si registrano automaticamente mediante 
l'oggetto TRemoteDataModuleRegistrar nel metodo UpdateRegistry dell'oggetto di 
implementazione. E possibile impedire questa registrazione impostando a false la 
proprieta EnableWeb dell'oggetto. 

Le connessioni web possono trarre vantaggio dalla centralizzazione degli oggetti. Cio 
consente il server di creare un sistema centralizzato limitato di istanze 
dell'application server, disponibili per le richieste dei client. Centralizzando gli 
application server, il server non utilizza risorse per il modulo dati e per la 
connessione al database se non quando sono necessarie. Per maggiori informazioni 
sulla centralizzazione di oggetti, consultare la sezione "Centralizzazione di moduli 
dati remoti" a pagina 29-8. 

A differenza di altri componenti connection, se la connessione viene stabilita via 
HTTP non e possibile utilizzare callback. 

Utilizzo di connessioni SOAP 

SOAP e il protocollo che e alia base del supporto della VCL o della CLX per le 
applicazioni Web Service. SOAP smista le chiamate ai metodi utilizzando una 
codifica XML. Le connessioni SOAP utilizzano HTTP come protocollo di trasporto. 

Le connessioni SOAP hanno il vantaggio di funzionare nelle applicazioni 
multipiattaforma perche sono supportati sia in Windows che in Linux. Poiche le 
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connessioni SOAP utilizzano HTTP, hanno gli stessi vantaggi delle connessioni Web: 
HTTP offre un minimo comun denominatore disponibile su tutti i client e i client 
possono comunicare con un application server protetto da un "firewall". Per ulteriori 
informazioni sull'utilizzo di SOAP per la distribuzione di applicazioni, vedere il 
Capitolo 36, "Utilizzo dei Web Services". 

Come nel caso delle conenssioni HTTP, se la connessione viene stabilita via SOAP 
non e possibile utilizzare callback. Inoltre le connessioni SOAP impongono il limite 
di un solo modulo dati remoto nell'application server. 

Creazione di un'applicazione multi-tier 



Le fasi fondamentali per la creazione di un'applicazione database multi-tier sono 

1 Creare l'application server. 

2 Registrare o installare l'application server. 

3 Creare un'applicazione client. 

La sequenza di creazione e importante. L'application server deve essere creato ed 
eseguito prima della creazione di un client. In fase di progettazione occorre collegarsi 
all'application server per collaudare il client. E possibile, ovviamente, creare un client 
senza specificare l'application server in fase di progettazione, e fornire solo il nome 
del server in fase di esecuzione. Pero, cosi facendo, non sara possibile capire se 
l'applicazione funziona come previsto nel codice in fase di progettazione, e non si 
potranno scegliere i server e i provider usando l'Object Inspector. 

Se non si sta creando l'applicazione client sullo stesso sistema del server e non si sta 
utilizzando una connessione DCOM o socket, pud essere necessario registrare o 
installare l'application server sul sistema client. Cio associa il componente connection 
all'application server in fase di progettazione, consentendo cosi di scegliere i nomi 
del server e del provider da un elenco a discesa nell'Object Inspector. (Se si sta 
utilizzando una connessione Web, SOAP o socket, il componente connection 
recupera i nomi dei provider registrati dalla macchina server). 

Creazione dell'application server 



La creazione di un'application server e analoga alia creazione della maggior parte 
della applicazioni database. La differenza principale e che l'application server 
include un modulo dati remoto. 

Per creare un'application server, fare quanto segue: 

1 Avviare un nuovo progetto: 

• Se come protocollo di trasporto si utilizza SOAP, il progetto dovrebbe essere 
una nuova applicazione Web Service. Scegliere File I New I Other, e sull pagina 
WebServices della finestra di dialogo New items, scegliere SOAP Server 
application. 
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• Per qualsiasi altro protocollo di trasporto, e sufficiente scegliere File I New I 
Application. 

Salvare il nuovo progetto. 

2 Aggiungere un nuovo modulo dati remoto al progetto. Dal menu principale, 
scegliere File I New I Other, e sulle pagine MultiTier o WebServices della finestra di 
dialogo New Items selezionare 

• Remote Data Module per la creazione di un Automation server COM a cui i 
client possano accedere usando DCOM, HTTP o socket. 

• Transactional Data Module per la creazione di moduli dati remoti funzionanti 
in ambiente MTS o COM+. Le connessioni possono essere formate utilizzando 
DCOM, HTTP o i socket. Tuttavia, solo DCOM supporta i servizi per la 
sicurezza. 

• SOAP Server Data Module se si sta creando un server SOAP in 
un'applicazione Web Service. 

Per informazioni piu dettagliate sulla configurazione di un modulo dati remoto, 
consultare "Impostazione del modulo dati remoto" a pagina 29-14. 

Se si sceglie Remote Data Module oppure Transactional Data Module, il Wizard 
crea anche uno speciale oggetto COM Automation che contiene un riferimento al 
modulo dati remoto, utilizzato per cercare i provider. Tale oggetto e detto oggetto 
di implementazione. Nel caso di moduli dati SOAP, non v'e necessita di un 
oggetto di implementazione separato, in quanto il modulo dati implementa esso 
stesso l'interfaccia IAppServerSOAP. 

3 Collocare gli appositi componenti dataset nel modulo dati e impostarli per 
accedere al database server. 

4 Per ciascun dataset, collocare un componente TDataSetProvider sul modulo dati. 
Questo provider e necessario per eseguire il brokering delle richieste dei client e la 
creazione di pacchetti dati. Impostare la proprieta DataSet per ogni componente 
provider al nome del dataset a cui accedere. E possibile impostare ulteriori 
proprieta per il provider. Per informazioni piu dettagliate sull'impostazione di un 
provider, consultare il Capitolo 28, "Uso di componenti provider". 

Se si gestiscono dati provenieti da documenti XML, e possibile utilizzare un 
componente TXMLTransformProvider invece di un dataset e di un componente 
TDataSetProvider. Se si utilizza TXMLTransformProvider, impostare la proprieta 
XMLDataFile specificando il documento XML da cui provengono i dati e su cui 
applicare gli aggiornamenti. 

5 Scrivere il codice dell' application server per implementare gli eventi, le regole 
condivise di gestione, la convalida condivisa dei dati e la sicurezza condivisa. 
Durante la stesura del codice, si potrebbe 

• Estendere l'interfaccia dell'application server in modo da fornire 
all'applicazione client un ulteriore modo per chiamare il server. L'estensione 
dell'interfaccia dell'application server e descritta in "Estensione dell'interfaccia 
dell'application server" a pagina 29-17. 
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• Fornire un supporto per le transazioni in aggiunta alle transazioni 
automaticamente create al momenta dell'applicazione degli aggiornamenti. II 
supporto delle transazioni nella applicazioni database multi-tier e descritto in 
"Gestione delle transazioni nelle applicazioni multi-tiered" a pagina 29-18. 

• Creare relazioni master/ detail tra i dataset neU'application server. Le relazioni 
master/ detail sono descritte in "Supporto delle relazioni master /detail" a 
pagina 29-19. 

• Assicurasi che l'application server sia senza stato. La gestione di informazioni 
di stato e descritta in "Supporto delle informazioni di stato nei moduli dati 
remoti" a pagina 29-20. 

• Dividere l'application server in piu moduli dati remoti. L'utilizzo di piu moduli 
dati remoti e descritto in "Uso di piu moduli dati remoti" a pagina 29-21. 

6 Salvare, compilare e registrare o installare l'application server. La registrazione di 
un application server e descritta in "Registrazione dell'application server" a 
pagina 29-22. 

7 Se l'applicazione server non usa DCOM o SOAP, occorre installare il software di 
runtime che riceve i messaggi del client, istanzia il modulo dati remoto e smista le 
chiamate all'interfaccia. 

• Per i socket TCP/IP questo e un'applicazione socket dispatcher, Scktsrvr.exe. 

• Per le connessioni HTTP questo e httpsrvr.dll, una DLL IS API /NS API che deve 
essere installata con il server Web. 



Impostazione del modulo dati remoto 



Quando si crea il modulo dati remoto, occorre fornire alcune informazioni che 
indicano come rispondere alle richieste del client. Tali informazioni variano, a 
seconda del tipo di modulo dati remoto. 

Configurazione del modulo dati remoto nel caso non sia transazionale 

Per aggiungere un modulo dati remoto basato su COM alia applicazione senza 
includere attributi transazionali, scegliere File I New I Other e, dalla pagina Multitier 
della finestra di dialogo New Items, selezionare l'opzione Remote Data Module. 
Verra visualizzato Remote Data Module wizard. 

Bisogna fornire un nome di classe per il modulo dati remoto.Questo e il nome base di 
un discendente di TCRemoteDataModule che viene creato dall'applicazione. Esso e 
anche il nome base dell'interfaccia dell'application server. Ad esempio, se si usa 
come nome di classe MyDataServer, il wizard crea una nuova unit che dichiara 
TMyDataServer, un discendente di TCRemoteDataModule. Nell'header della unit, il 
Wizard dichiara inoltre una classe di implementazione (TMyDataServerlmpl) che 
implementa IMyDataServer, un discendente di IAppServer. 

Alia nuova interfaccia si possono aggiungere proprieta e metodi propri. Per ulteriori 
informazioni, consultare "Estensione dell'interfaccia dell'application server" a 
pagina 29-17. 
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Occorre specif icare il modello di threading nel Remote Data Module wizard. E 
possibile scegliere Single-threaded, Apartment-threaded, Free-threaded o Both. 

• Se si sceglie Single-threaded, COM assicura che viene soddisfatta solo una 
richiesta del client alia volta. Non ci si deve preoccupare delle richieste dei client 
che interferiscono tra loro. 

• Se si sceglie Apartment-threaded, COM assicura che qualsiasi istanza del modulo 
dati remoto soddisfera una richiesta alia volta. Quando si scrive del codice in una 
libreria Apartment-threaded, occorre prestare attenzione al rischio di conflitti tra 
thread se si usano variabili o oggetti globali non contenuti nel modulo dati remoto. 
Questo e il modello consigliato se si stanno utilizzando dataset BDE. (Si noti che, 
per gestire tutti gli aspetti relativi al threading sui dataset BDE, sara necessario un 
componente session con la proprieta AutoSessionName impostata a true). 

• Se si sceglie Free-threaded, l'applicazione puo ricevere richieste simultanee di 
client su diversi thread. Bisogna accertarsi che l'applicazione sia thread-safe. Dal 
momento che piu client possono accedere contemporaneamente al modulo dati 
remoto, occorre prestare attenzione ai dati dell'istanza (proprieta , oggetti 
contenuti, e cosi via) e alle variabili globali. Questo modello e consigliabile se si sta 
utilizzando un dataset ADO. 

• Se si sceglie Both, la libreria funziona esattamente come quando si sceglie Free- 
threaded, ma con un'eccezione: tutte le callback (le chiamate alle interfacce client) 
vengono serializzate automaticamente. 

• Se si sceglie Neutral, il modulo dati remoto puo ricevere chiamate simultanee su 
thread separati, come nel modello Free-threaded, ma COM garantisce che non vi 
saranno mai due thread che accederanno contemporaneamente alio stesso 
metodo. 

Configurazione di un modulo dati remoto transazionale 

Per aggiungere un modulo dati remoto all'applicazione quando si utilizzera MTS o 
COM+, scegliere il comando File I New I Other e selezionare il comando 
Transactional Data Module dalla pagina Multitier della finestra di dialogo New 
Items. Apparira il wizard Transactional Data Module. 

Bisogna fornire un nome di classe per il modulo dati remoto.Questo e il nome base di 
un discendente di TCRemoteDataModule che viene creato dall'applicazione. Esso e 
anche il nome base dell'interfaccia dell'application server. Ad esempio, se si usa 
come nome di classe MyDataServer, il wizard crea una nuova unit che dichiara 
TMyDataServer, un discendente di TCRemoteDataModule. Nell'header della unit, il 
wizard dichiara anche la classe di implementazione, (TMyDataServerlmpl) che 
implementa sia IMyDataServer (un discendente di IAppServer) sia IObjectControl (che e 
richiesto da tutti gli oggetti transazionali). TMyDataServerlmpl include un membro 
dati per l'interfaccia IObjectContext, che si potra utilizzare per gestire transazioni, 
controllare la sicurezza, e cosi via. 

Alia nuova interfaccia si possono aggiungere proprieta e metodi propri. Per ulteriori 
informazioni, consultare "Estensione dell'interfaccia dell'application server" a 
pagina 29-17. 
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Occorre specificare il modello di threading nel wizardTransactional Data Module. 
Scegliere tra Single, Apartment o Both. 

• Se si sceglie Single, le richieste dei client vengono serializzate in modo che 
l'applicazione ne soddisfi una alia volta. Non ci si deve preoccupare delle richieste 
dei client che interferiscono tra loro. 

• Se si sceglie Apartment, il sistema assicura che qualsiasi istanza del modulo dati 
remoto soddisfi una richiesta alia volta e che le chiamate usino sempre lo stesso 
thread. Occorre prestare attenzione al rischio di conflitti tra thread se si usano 
variabili o oggetti globali non contenuti nel modulo dati remoto. Anziche usare 
variabili globali, si pud ricorrere alio Shared Property manager. Per maggiori 
informazioni sullo Shared Property manager, consultare il paragrafo "Shared 
property manager" a pagina 44-7. 

• Se si sceglie Both, MTS chiama l'interfaccia dell'application server come quando si 
sceglie Apartment. Tuttavia, tutte le callback diretie alle applicazioni client 
vengono serializzate, cosicche non ci si deve preoccupare di quelle che 
interferiscono l'una con l'altra. 

II modello Apartment sotto MTS o COM+ e diverso dal modello corrispondente sotto 
DCOM. 

Bisogna anche specificare gli attributi di transazione del modulo dati remoto. E 
possibile scegliere una delle seguenti opzioni: 

• Requires a transaction. Quando si seleziona questa opzione, ogni volta che un 
client usa l'interfaccia dell'application server, quella chiamata viene eseguita nel 
contesto di una transazione. Se il chiamante fornisce una transazione, non c'e 
alcuna necessita di crearne una nuova. 

• Requires a new transaction. Quando si seleziona questa opzione, ogni volta che un 
client usa l'interfaccia dell'application server, viene creata automaticamente una 
nuova transazione per quella chiamata. 

• Supports transactions. Quando si seleziona questa opzione, l'application server 
puo essere usato nel contesto di una transazione, ma il chiamante deve fornire la 
transazione quando richiama l'interfaccia. 

• Does not support transactions. Quando si seleziona questa opzione, l'application 
server non puo essere usato nel contesto delle transazioni. 

Configurazione di TSoapDataModule 

Per aggiungere all'applicazione un componente TSoapDataModule, scegliere File I 
New I Other e, dalla pagina WebService della finestra di dialogo New Items, 
selezionare l'opzione SOAP Data Module. Viene visualizzato SOAP data module 
wizard. 

Bisogna fornire un nome di classe per il modulo dati SOAP. Questo e il nome di base 
di un discendente di TSoapDataModule che viene creato dall'applicazione. Ad 
esempio, se si usa come nome di classe MyDataServer, il wizard crea una nuova unit 
che dichiara TMyDataServer , un discendente di TSoapDataModule. Questa nuova 
classe eredita da TSoapDataModule un'implementazione di IAppServer e di 
IAppServerSOAP. 
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A differenza degli altri moduli dati remoti, i moduli dati SOAP non implementano 
un'interfaccia che discende da IAppServer o da IAppServerSOAP. Questo e dovuto alle 
differenze nel modo in cui le applicazioni Web Service smistano le chiamate in arrivo 
alle interfacce. Invece, utilizzando Add Web Service wizard e possibile alia propria 
applicazione nuove interfacce. 

Per utilizzare TSoapDataModule, il nuovo modulo dati dovrebbe essere aggiunto a 
un'applicazione Web Service. L'interfaccia IAppServerSOAP e un'interfaccia 
richiamabile, registrata nel codice di inizializzazione della nuova unit. Cio permette 
al componente invoker nel modulo Web principale di inoltrare tutte le chiamate in 
arrivo al modulo dati. 

Se si desidera che l'application server risponda a client che sono stati scritti 
utilizzando Kylix 2 o Delphi 6 (prima della patch di aggiornamento 2), e necessario 
aggiungere del codice per registrare l'interfaccia IAppServer. Individuare il codice di 
avvio che registra IAppServerSOAP. Immediatamente dopo tale chiamata di 
registrazione, aggiungere una chiamata alia funzione globale 

RegDeflAppServerlnvClass, la quale registra il modulo dati come implementazione di 
IAppServer. 

Estensione dell'interfaccia dell'application server 



Le applicazioni client dei server basati su COM interagiscono con l'application server 
creando o connettendosi alia classe dell'implementazione creata da data module 
Wizard. Esse usano l'interfaccia del modulo dati remoto come base per tutte le 
comunicazioni con l'application server. 

Se si utilizza un application server basato su COM, e possibile aggiungere elementi 
all'interfaccia della classe dell'implementazione in modo da fornire un supporto 
aggiuntivo alle applicazioni client. Questa interfaccia e un discendente di IAppServer 
e viene generata automaticamente dal wizard quando si crea il modulo dati remoto. 

Per aggiungere elementi all'interfaccia del modulo dati remoto, usare l'editor delle 
librerie di tipi. Per maggiori informazioni sull'utilizzo dell'editor delle librerie di tipi, 
consultare il Capitolo 39, "Funzionamento delle librerie di tipi". 

Quando si aggiungono elementi a un'interfaccia COM, le modifiche vengono 
aggiunte al codice sorgente della unit e al file della libreria di tipi (.TLB). 

E necessario salvare esplicitamente il file .TLB scegliendo Refresh nel Type Library 
editor e salvando poi le modifiche dall'IDE. 

Una volta aggiunta l'interfaccia della classe dell'implementazione, si devono 
individuare le proprieta e i metodi che sono stati aggiunti alia propria classe 
dell'implementazione. Quindi, si deve aggiungere il codice per portare a termine 
questa implementazione completando i corpi dei nuovi metodi. 

Le applicazioni client chiamano le estensioni dell'interfaccia usando la proprieta 
AppServer del loro componente connection. Per ulteriori informazioni su come 
eseguire questa operazione, consultare "Chiamata delle interfacce del server" a 
pagina 29-29. 
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Aggiunta di callback all'interfaccia dell'application server 

Si pud consentire all'application server di chiamare l'applicazione client 
introducendo una callback. A questo scopo, l'applicazione client passa un'interfaccia 
a uno dei metodi dell'application server, e l'application server, in seguito, chiama 
questo metodo quando occorre. Comunque, se le estensioni all'interfaccia della classe 
implementation includono callback, non e possibile utilizzare una connessione 
basata su HTTP o su SOAP. TWebConnection e TSoapConnection non supportano le 
callback. Se si sta utilizzando una connessione basata su socket, le applicazioni client 
devono indicare se utilizzano o meno callback mediante l'impostazione della 
proprieta SupportCallbacks. Tutti gli altri tipi di connessione supportano 
automaticamente le callback. 

Estensione dell'interfaccia transazionale di un application server 

Quando si utilizzano le transazioni o l'attivazione just-in-time, occorre accertarsi che 
tutti i nuovi metodi chiamino il metodo SetComplete di IObjectContext per indicare 
che hanno terminato il proprio compito. Cio consente di completare le transazioni e 
consente all'application server di essere disattivato. 

Inoltre, i nuovi metodi non possono restituire alcun valore che consenta al client di 
comunicare direttamente con gli oggetti o con le interfacce sull'application server, a 
meno che non forniscano un riferimento sicuro. Se si sta utilizzando un modulo dati 
MTS senza stato, la dimenticanza dell'utilizzo di un riferimento sicuro pud condurre 
a errore critici in quanta non e possibile garantire che il modulo dati remoto sia 
attivo. Per maggiori informazioni sui riferimenti sicuri, consultare "Passaggio di 
riferimenti a oggetti" a pagina 44-27. 

Gestione delle transazioni nelle applicazioni multi-tiered 



Quando le applicazioni client applicano gli aggiornamenti all'application server, il 
componente provider effettua automaticamente il wrap del processo di applicazione 
degli aggiornamenti e di risoluzione degli errori in una transazione. Questa 
transazione viene inoltrata se il numero di record problematici non supera il valore 
MaxErrors specificato come argomento per il metodo Applyllpdates. Altrimenti, tutto 
viene annullato. 

Inoltre, si puo aggiungere il supporto per le transazioni all'applicazione server 
aggiungendo ricorrendo a un componente di connessione al database oppure 
gestendo direttamente la transazione tramite l'invio di comandi SQL al server di 
database. Questo funziona nello stesso modo in cui si gestiscono le transazioni in 
un' applicazione two-tier. Per ulteriori informazioni su questo tipo di controllo della 
transazione, consultare "Gestione delle transazioni" a pagina 21-6. 

Se si usa un modulo dati transazionale, e possibile ampliare il supporto transazionale 
usando le transazioni MTS o COM+. Queste possono includere qualsiasi logica di 
gestione sull'application server, non solo l'accesso al database. Inoltre, poiche 
supportano gli invii in due fasi, le transazioni possono interessare piu database. 
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Solamente i componenti di accesso ai dati basati su BDE e ADO supportano l'invio a 
due fasi. Non utilizzare componenti InterbaseExpress o db Express se si desidera 
avere transazioni che coinvolgono piu database. 

Quando si utilizza BDE, l'invio in due fasi viene implementato completamente solo 
sui database Oracle7 e MS-SQL. Se la transazione riguarda piu database, alcuni dei 
quali sono server remoti diversi da Oracle7 o MS-SQL, la transazione corre il rischio 
di una riuscita solo parziale. All'interno di un qualsiasi database, tuttavia, ci sara 
sempre un supporto transazionale. 

Per impostazione predefinita, tutte le chiamate di IAppServer a un modulo dati 
transazionale sono transazionali. E necessario solamente impostare l'attributo della 
transazione del modulo dati per indicare che deve partecipare alle transazioni. 
Inoltre, e possibile estendere l'interfaccia dell'application server in modo da 
includere le chiamate ai metodi che incapsulano le transazioni definite dal 
p rogrammator e . 

Se l'attributo della transazione indica che l'application server richiede una 
transazione, ogni volta che un client chiama un metodo della propria interfaccia, 
viene inglobato automaticamente in una transazione. Tutte le chiamate del client 
all'application server vengono quindi elencate in quella transazione finche non si 
indica che e completata. Queste chiamate o riescono completamente oppure vengono 
annullate. 

Non si devono abbinare le transazioni MTS o COM+ alle transazioni esplicite create 
da un componente di connessione al database o mediante un comando SQL esplicito. 
Quando il modulo dati transazionale viene elencato in una transazione, elenca 
automaticamente anche tutte le chiamate al database contenute nella transazione. 

Per ulteriori informazioni sull'uso delle transazioni MTS e COM+, consultare il 
paragrafo "Supporto delle transazioni MTS e COM+" a pagina 44-10. 

Supporto delle relazioni master/detail 



E possibile creare una relazione master/ detail tra i dataset client in un'applicazione 
client nello stesso modo utilizzato per impostarle quando si utilizza un qualsiasi 
dataset di tipo tabella. Per ulteriori informazioni sull'impostazione di relazioni 
master /detail, consultare "Creazione di relazioni master /detail" a pagina 22-36. 

Tuttavia, questo approccio presenta due importanti svantaggi: 

• La tabella detail deve recuperare e memorizzare tutti i suoi record dall'application 
server anche se usa solo un set detail alia volta. (Questo problema puo essere 
mitigato mediante l'uso di parametri. Per ulteriori informazioni, consultare 
"Limitazione dei record mediante parametri" a pagina 27-31.) 

• E molto difficile applicare gli aggiornamenti, perche i dataset client li applicano a 
livello di dataset e perche gli aggiornamenti master/ detail riguardano piu dataset. 
Anche in un ambiente two-tier, dove si puo usare il componente di connessione al 
database per applicare gli aggiornamenti a piu tabelle con un'unica transazione, 
l'applicazione degli aggiornamenti nelle schede master/ detail e complessa. 
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Nelle applicazioni multi-tier questi problemi possono essere evitati usando le tabelle 
annidate per rappresentare la relazione master/ detail. A questo scopo, durante la 
fase di fornitura dai dataset, occorre impostare una relazione master/ detail tra i 
dataset sull'application server. Quindi, si deve impostare la proprieta DataSet del 
componente provider alia tabella master. Per utilizzare tabelle annidate per 
rappresentare le relazioni di master/detail durante la fornitura a partire da 
documenti XML, utilizzare un file di trasformazione che definisce i set di dettaglio 
annidati. 

Quando i client chiamano il metodo GetRecords del provider, questi include 
automaticamente i dataset di dettaglio come campo DataSet nei record del pacchetto 
dati. Quando i client chiamano il metodo ApplyUpdates del provider, questo gestisce 
automaticamente l'applicazione degli aggiornamenti nel corretto ordine. 

Supporto delle informazioni di stato nei moduli dati remoti 



L'interfaccia IAppServer, che i client dataset utilizzano per comunicare con i provider 
sull'application server, e quasi sempre senza stato. Se un'applicazione e senza stato, 
non "ricorda" niente di cio che e successo nelle precedenti chiamate da parte del 
client. Questa qualita di essere senza stato risulta utile se si vogliono centralizzare le 
connessioni al database in un modulo dati transazionale, in quanto l'application 
server non ha la necessita di riconoscere distintamente le informazioni persistenti, 
come, ad esempio, il record corrente, tra una connessioni al database e la successiva. 
Analogamente, questa qualita di essere senza stato diventa importante quando si 
condividono istanze di moduli dati remoti tra diversi client, come accade con 
l'attivazione just-in-time o con la centralizzazione degli oggetti. I moduli dati SOAP 
devono essere senza stato. 

A volte, tuttavia, potrebbe essere necessario conservare le informazioni di stato tra 
una chiamata all'application server e l'altra. Per esempio, quando si richiedono dati 
utilizzando il recupero incrementale, il provider sull'application server deve 
"ricordare" le informazioni delle chiamate precedenti (qual e il record corrente). 

Prima e dopo ogni chiamata all'interfaccia IAppServer effettuata dal dataset client 
(AS_ApplylIpdates, AS_Execute, AS_GetParams, AS_GetRecordso AS_RowRequest), 
l'application server riceve un evento in cui puo trasmettere o recuperare 
informazioni di stato personalizzate. Analogamente, i provider, prima e dopo ogni 
risposta a queste chiamate generate dal client, ricevono eventi in cui possono reperire 
o trasmettere informazioni di stato personalizzate. Utilizzando questo meccanismo, e 
possibile comunicare informazioni di stato persistenti tra le applicazioni client e 
l'application server, anche se l'application server e senza stato. 

Ad esempio, si consideri un dataset che rappresenta la seguente query 
parametrizzata: 

SELECT * from CUSTOMER WHERE CUSTJJO > :MinVal ORDER BY CUSTJJO 

Per consentire il prelievo incrementale in un application server senza stato si puo fare 
quanto segue: 

• Quando il provider assembla un set di record in un pacchetto dati, annota il valore 
di CUST_NO sull'ultimo record nel pacchetto: 
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TRemoteDataModulel: :DataSetProviderlGetData (TObject *Sender, TCustomClientDataSet *DataSet) 

{ 

DataSet->Last ( ) ; // move to the last record 

TComponent *pProvider = dynamic_cast<TComponent *> (Sender); 

pProvider->Tag = DataSet->FieldValues[ ,, CUST_NO n ] ; 

} 

• II provider invia questo ultimo valore CUST_NO al client dopo avere mandato il 
pacchetto dati: 

TRemoteDataModulel: :DataSetProviderlAfterGetRecords (TObject *Sender, OleVariant &OwnerData) 
{ 

TComponent *pProvider = dynamic_cast<TComponent *> (Sender); 
OwnerData = pProvider->Tag; 

} 

• Sul client, il dataset client salva questo ultimo valore di CUST_NO: 

TDataModulel: :ClientDataSetlAfterGetRecords (TObject *Sender, OleVariant SOwnerData) 

{ 

TComponent *pDS = dynamic_cast<TComponent *>(Sender); 
pDS->Tag = OwnerData; 

} 

• Prima di prelevare un pacchetto dati, il client invia l'ultimo valore di CUST_NO 
che ha ricevuto: 

TDataModulel: :ClientDataSetlBeforeGetRecords (TObject *Sender, OleVariant &OwnerData) 

{ 

TClientDataSet *pDS = dynamic_cast<TClientDataSet *> (Sender); 
if ( !pDS->Active) 

return ; 
OwnerData = pDS->Tag; 

} 

• Infine, sul server, il provider utilizza l'ultimo CUST_NO inviato come valore 
minimo nella query: 

TRemoteDataModulel: :DataSetProviderlBeforeGetRecords (TObject *Sender, OleVariant &OwnerData) 

{ 

if ( IVarlsEmpty (OwnerData) ) 
{ 

TDataSetProvider *pProv = dynamic_cast<TDataSetProvider *>(Sender); 
TSQLDataSet *pDS = (dynamic_cast<TSQLDataSet *>(pProv->DataSet) ; 
pDS->Params->ParamValues [ "MinVal" ] = OwnerData; 
pDS->Refresh( ) ; // force the query to reexecute 

} 

} 

Uso di piu moduli dati remoti 



Potrebbe essere necessario strutturare l'application server in modo che utilizzi piu 
moduli dati remoti. L'utilizzo di piu moduli dati remoti permette di suddividere il 
codice, organizzando un grosso application server in piu unit, in cui ogni unit e 
sufficientemente indipendente. 
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Benche sia sempre possibile creare piu moduli dati remoti sull'application server che 
operano in modo indipendente, un particolare componente connection sulla pagina 
DataSnap della Component Palette da la possibility di usare un modello in cui si ha 
un modulo dati remoto "genitore" principale che indirizza le connessioni dai client 
ad altri moduli dati remoti "figlio". Questo modello richiede che si utilizzi un 
application server basato su COM. 

Per creare il modulo dati remoto genitore, e necessario ampliare la sua interfaccia 
IAppServer, aggiungendo proprieta che espongono le interfacce dei moduli dati 
remoti figlio. Vale a dire, per ogni modulo dati remoto figlio, si deve aggiungere una 
proprieta all'interfaccia del modulo dati genitore il cui valore e l'interfaccia 
IAppServer del modulo dati figlio. 

Per ulteriori informazioni sull'estensione dell'interfaccia dell'parent remote, 
consultare "Estensione dell'interfaccia dell'application server" a pagina 29-17. 

r^) Potrebbe anche esere necessario ampliare l'interfaccia di ogni modulo dati figlio, 
y | esponendo l'interfaccia del modulo dati genitore o le interfacce degli altri moduli dati 
figlio. Cio permette ai diversi moduli dati nell'application server di comunicare l'uno 
l'altro piu liberamente. 

Una volta aggiunte al modulo dati remoto principale le proprieta che rappresentano i 
moduli dati remoti figlio, le applicazioni client devono piu stabilire connessioni 
separate con ogni modulo dati remoto sull'application server. Esse condividono 
invece una singola connessione al modulo dati remoto genitore, il quale al sua volta 
indirizza messaggi ai moduli dati "figlio". Poiche ogni applicazione client utilizza la 
stessa connessione per ogni modulo dati remoto, i moduli dati remoti possono 
condividere una singola connessione database, risparmiando risorse. Per 
informazioni sulle modalita di condivisione di una singola connessione da parte 
delle applicazioni figlio, vedere "Connessione a un application server che utilizza piu 
moduli dati" a pagina 29-30. 

Registrazione dell'application server 



Prima che le applicazioni client possano individuare e utilizzare un application 
server, deve essere registrate o installato. 

• Se l'application server usa come protocollo di comunicazione DCOM, HTTP o i 
socket, si comporta come un Automation server e deve essere registrato come un 
qualunque altro server COM. Per informazioni sulla registrazione di un server 
COM, consultare "Registrazione di un oggetto COM" a pagina 41-17. 

• Se si utilizza un modulo dati transazionale, non si registra l'application server. Lo 
si installera , invece, insieme con MTS o COM+. Per maggiori informazioni 
sull'installazione di oggetti transazionali, consultare il paragrafo "Installazione di 
oggetti transazionali" a pagina 44-29. 

• Se l'application server utilizza SOAP, l'applicazione deve essere un'applicazione 
Web Service. Come tale, deve essere registrata con il Web Server, in modo che 
riceva i messaggi HTTP in arrive Inoltre, e possibile pubblicare un documento 
WSDL che descrive le interfacce richiamabili nell'applicazione. Per informazioni 
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sull'esportazione di un documento WSDL per un'applicazione Web Service, 
vedere "Generazione di documenti WSDL per un'applicazione Web Service" a 
pagina 36-16. 

Creazione dell'applicazione client 



Per molti aspetti la creazione di un'applicazione client multi-tier e simile alia 
creazione un client two-tier che utilizza un dataset client per memorizzare in cache 
gli aggiornamenti. La princpale differenza consiste nel fatto che un'applicazione 
multi-tier utilizza un componente connection per stabilire un collegamento con 1' 
application server. 

Per creare un'applicazione client multi-tier, si deve avviare un nuovo progetto e 
eseguire queste operazioni: 

1 Aggiungere un nuovo modulo dati al progetto. 

2 Collocare un componente connection nel modulo dati. II tipo di componente 
connessione che si aggiunge dipende dal protocollo di comunicazione che si vuole 
utilizzare. Per i dettagli, consultare "Struttura dell'applicazione client" a 
pagina 29-4. 

3 Impostare le proprieta del componente connessione in modo da specificare 
l'application server con cui si dovrebbe istituire una connessione. Per ulteriori 
informazioni sulla configurazione dei componenti connessione, consultare la 
sezione "Connessione all'application server" a pagina 29-24. 

4 Impostare le altre proprieta del componente connection come richiesto per 
l'applicazione. Per esempio, si puo impostare la proprieta ObjectBroker per 
consentire al componente connection di scegliere dinamicamente da piu server. 
Per maggiori informazioni circa l'utilizzo di componenti connection, consultare 
"Gestione delle connessioni al server" a pagina 29-27 

5 Collocare tutti i componenti TClientDataSet necessari sul modulo dati, e impostare 
la proprieta RemoteServer per ciascun componente al nome del componente 
connection collocato al Punto 2. Per una completa introduzione ai dataset client, 
consultare il Capitolo 27, "Utilizzo dei dataset client". 

6 Impostare la proprieta ProviderName di ciascun componente TClientDataSet. Se il 
componente connection viene collegato all'application server in fase di 
progettazione, e possibile scegliere i provider disponibili dell'application server 
dall'elenco a discesa della proprieta ProviderName. 

7 Continuare esattamente come se si stesse creando una qualsiasi altra applicazione 
database. Vi sono alcune funzioni aggiuntive disponibili per client delle 
applicazioni multi-tier: 

• L'applicazione potrebbe dover chiamare direttamente l'application server. 
Queste operazioni sono descritte in "Chiamata delle interf acce del server" a 
pagina 29-29. 

• Molto probabilmente si vorranno utilizzare le particolari funzionalita dei 
dataset client che supportano la loro interazione con i componenti provider. 
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Queste funzionalita sono descritte nella sezione "Uso di un dataset client con 
un provider di dati" a pagina 27-26. 

Connessione aH'application server 



Per stabilire e mantenere una connessione a un application server, un'applicazione 
client usa uno o piu componenti connection. Questi componenti si trovano sulle 
pagine DataSnap o WebServices della Component palette. 

Un componente connection puo essere utilizzato per 

• Identificare il protocollo per la comunicazione con l'application server. Ogni tipo 
di componente connection rappresenta un protocollo di comunicazione differente. 
Per informazioni dettagliate sui vantaggi e sui vincoli dei protocolli disponibili, 
consultare il paragrafo "Scelta di un protocollo di connessione" a pagina 29-9. 

• Indicare come individuare la macchina server. I dettagli per l'identificazione della 
macchina server variano a seconda del protocollo. 

• Identificare l'application server sulla macchina server. 

• Se non si sta utilizzando SOAP, identificare il server usando la proprieta 
ServerName o ServerGUID. ServerName identifica il nome di base della classe 
specificata al momento della creazione del modulo dati remoto sull'application 
server. Per informazioni dettagliate su come viene specificato questo valore sui 
server, consultare il paragrafo "Impostazione del modulo dati remoto" a 
pagina 29-14. Se il server viene registrato o installato sulla macchina client, o se il 
componente connection viene collegato alia macchina server, e possibile impostare 
la proprieta ServerName in fase di progettazione scegliendo da un elenco a discesa 
nell' Object Inspector. ServerGUID specif ica il GUID dell'interfaccia del modulo 
dati remoto. E possibile consultare questo valore usando il Type Library editor. 

Se si utilizza SOAP, il server e identificato nello URL che si usa per individuare la 
macchina server. Seguire le istruzioni riportate in "Specifica di una connessione 
con SOAP" a pagina 29-26. 

• Gestire le connessioni al server. I componenti connection possono essere usati per 
creare o abbandonare le connessioni e per chiamare le interfacce dell'application 
server. 

Normalmente, l'application server e su una macchina diversa dall'applicazione 
client, ma anche se il server risiede sulla stessa macchina dell'applicazione client (per 
esempio, durante la costruzione e la verifica dell'intera applicazione multi-tier), e 
sempre possibile usare il componente connection per identificare l'application server 
per nome, specificare una macchina server e usare l'interfaccia dell'application 
server. 

Specifica di una connessione con DCOM 

Quando si usa DCOM per comunicare con l'application server, le applicazioni client 
includono un componente TDCOMConnection per la connessione aH'application 
server. TDCOMConnection usa la proprieta ComputerName per identificare la 
macchina su cui risiede il server. 
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Quando ComputerName e vuota, il componente connection DCOM assume che 
l'application server risiede sulla macchina client o che l'application server ha un 
elemento nel registro di sistema. Se, quando si usa DCOM, non si fornisce un 
elemento del registro di sistema per l'application server sul client, e il server risiede 
su una macchina diversa dal client, bisogna indicare ComputerName. 

Anche quando c'e un elemento nel registro di sistema per l'application server, si puo 
specificare ComputerName per ridefinirlo. Cio puo essere particolarmente utile 
durante lo sviluppo, il collaudo e il debug. 

Se ci sono piu server da cui l'applicazione client puo scegliere, e possibile usare la 
proprieta ObjectBroker anziche specificare un valore per ComputerName. Per ulteriori 
informazioni, consultare il paragrafo "Brokering delle connessioni" a pagina 29-27. 

Se si fornisce il nome di un computer host o di un server inesistente, quando si cerca 
di aprire la connessione, il componente connection DCOM solleva un'eccezione. 

Specifica di una connessione con i socket 

E possibile stabilire una connessione all'application server usando i socket su 
qualsiasi macchina che abbia un indirizzo TCP/IP. Questo metodo ha il vantaggio di 
essere applicabile a piu macchine, ma non fornisce la possibility di usare tutti i 
protocolli di sicurezza. Quando si usano i socket, per collegarsi all'application server 
bisogna includere un componente TSocketConnection. 

TSocketConnection identifica la macchina server usando l'indirizzo IP o il nome 
deU'host del sistema server e il numero di porta del programma socket dispatcher 
(Scktsrvr.exe) che viene eseguito sulla macchina server. Per ulteriori informazioni 
sugli indirizzi IP e sui valori della porta, consultare "Descrizione dei socket" a 
pagina 37-3. 

Tre proprieta di TSocketConnection specificano queste informazioni: 

• Address specifica l'indirizzo IP del server. 

• Host specifica il nome dell'host del server. 

• Port specifica il numero di porta del programma socket dispatcher sull'application 
server. 

Address and Host si escludono a vicenda. L'impostazione di uno annulla il valore 
deU'altra. Per informazioni su quale dei due usare, consultare "Descrizione dell'host" 
a pagina 37-4. 

Se ci sono piu server da cui l'applicazione client puo scegliere, e possibile usare la 
proprieta ObjectBroker anziche specificare un valore per Address o Host. Per ulteriori 
informazioni, consultare il paragrafo "Brokering delle connessioni" a pagina 29-27. 

Per impostazione predefinita, il valore di Port e 211, che e il numero di porta 
predefinito del programma socket dispatcher che inoltra messaggi in arrivo 
all'application server. Se il socket dispatcher e stato configurato per usare un'altra 
porta, occorre impostare la proprieta Port in modo che corrisponda a quel valore. 

E possibile configurare la porta del socket dispatcher mentre e in esecuzione facendo 
clic sull'icona Borland Socket Server nella barra di stato e scegliendo Properties. 
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Sebbene le connessioni socket non consentano l'utilizzo di protocolli di sicurezza, e 
possibile personalizzare la connessione socket aggiungendo funzionalita di 
crittografia personalizzate. Per raggiungere questo risultato 

1 Creare un oggetto COM che supporti l'interfaccia IDatalntercept. Questa e 
un'interfaccia per la crittografia e la decifrazione dei dati. 

2 Registrare il nuovo server COM sulla macchina client. 

3 Impostare la proprieta InterceptName o InterceptGUID del componente connessione 
socket per specificare questo oggetto COM. 

4 Infine, fare clic destro sull'icona Borland Socket Server nella barra delle 
applicazioni, selezionare Properties e sulla pagina delle proprieta impostare 
Intercept Name o Intercept GUID al Progld o al GUID dell'interceptor. 

Tale meccanismo pud essere utilizzato anche per la compressione e la 
decompressione dei dati. 

Specifica di una connessione con HTTP 

E possibile stabilire una connessione all'application server usando HTTP su qualsiasi 
macchina che abbia un indirizzo TCP/IP. A differenza dei socket, tuttavia, HTTP 
consente di sfruttare la sicurezza SSL e di comunicare con un server protetto da un 
firewall. Quando si usano gli HTTP, per collegarsi all'application server bisogna 
includere un componente TWebConnection. 

II componente connessione Web stabilisce una connessione con l'applicazione Web 
server (httpsrvr.dll), che a sua volta comunica con l'application server. 
TWebConnection individua httpsrvr.dll utilizzando uno URL (Uniform Resource 
Locator). L'URL specifica il protocollo (http oppure, se si sta utilizzando la sicurezza 
SSL, https), il nome di host della macchina sui sui sono in secuzione il server web e 
httpsrvr.dll, e il percorso per l'applicazione Web server (httpsrvr.dll). Specificare 
questo valore utilizzando la proprieta URL. 

Quando si utilizza un componente TWebConnection, e necessario che wininet.dll sia 
installato sulla macchina client. Se e stato installato IE3, o una versione successiva, 
wininet.dll e presente nella directory System di Windows. 

Se il server Web richiede l'autenticazione, o si sta utilizzando un proxy server che 
richiede l'autenticazione, occorre impostare i valori delle proprieta UserName e 
Password in modo che il componente connessione possa effettuare il login. 

Se l'applicazione client puo scegliere tra piu server, invece di specificare un valore 
per la proprieta URL si puo utilizzare la proprieta ObjectBroker. Per ulteriori 
informazioni, consultare il paragrafo "Brokering delle connessioni" a pagina 29-27. 

Specifica di una connessione con SOAP 

E possibile stabilire una connessione a un application server SOAP utilizzando il 
componente TSoapConnection. TSoapConnection e molto simile a TWebConnection 
perche come protocollo di trasporto utilizza anch'esso HTTP. Percio, e possibile 
utilizzare TSoapConnection da qualsiasi macchina dotata di un indirizzo TCP/IP e 
sfruttare la sicurezza SSL per comunicare con un server protetto da un firewall. 



29-26 Guida alia programmazione 



Creazione dell'applicazione client 



II componente SOAP connection stabilisce una connessione con un Web Service che 
implementa l'interfaccia IAppServerSOAP e IAppServer. (La proprieta 
UseSOAP 'Adapter specifica qual e l'interfaccia prevista che dovrebbe essere 
supportata dal server). Se il server implementa l'interfaccia IAppServerSOAP, 
TSoapConnection converte tale interfaccia in un'interfaccia IAppServer per i dataset 
client. TSoapConnection individua questa applicazione Web server utilizzando uno 
URL (Uniform Resource Locator). L'URL specifica il protocollo (http oppure, se si sta 
utilizzando la sicurezza SSL, https), il nome di host della macchina sui sui e in 
secuzione il server web, il nome dell'applicazione Web Service, e un percorso che 
coincide con il nome di percorso del THTTPSoapDispatcher sull'application server. 
Specificare questo valore utilizzando la proprieta URL. 

Quando si utilizza un componente TSoapConnection, e necessario che wininet.dll sia 
installato sulla macchina client. Se e stato installato IE3, o una versione successiva, 
wininet.dll e presente nella directory System di Windows. 

Se il server Web richiede l'autenticazione, o si sta utilizzando un proxy server che 
richiede l'autenticazione, occorre impostare i valori delle proprieta UserName e 
Password in modo che il componente connessione possa effettuare il login. 

Brokering delle connessioni 

Se ci sono piu server basati su COM da cui l'applicazione client puo scegliere, si puo 
usare un Object Broker per individuare un sistema server disponibile. L'Object 
Broker conserva un elenco di server da cui il componente connection puo scegliere. 
Quando il componente connection ha bisogno di collegarsi a un application server, 
chiede all'Object Broker il nome di un computer (o un indirizzo IP, un nome di host, 
o URL). II broker fornisce un nome e il componente connection stabilisce una 
connessione. Se il nome fornito non va bene (per esempio, se il server e spento), il 
broker fornisce un altro nome, e cosi via, finche non viene stabilita una connessione. 

Una volata che il componente connection ha stabilito una connessione con un nome 
fornito dal broker, salva quel nome come valore della relativa proprieta 
(ComputerName, Address, Host, RemoteHost, o URL). Se in seguito il componente 
connection chiude la connessione ed ha poi bisogno di riaprirla, cerca di usare il 
valore di questa proprieta , e richiede un nuovo nome dal broker solo se la 
connessione non avviene. 

Per usare un Object Broker, si deve specificare la proprieta ObjectBroker del 
componente connection. Quando la proprieta ObjectBroker e impostata, il 
componente connection non salva il valore di ComputerName, Address, Host, 
RemoteHost, o URL su disco. 

Gestione delle connessioni al server 



Lo scopo principale dei componenti connection e di individuare e di effettuare la 
connessione all'application server. Poiche gestiscono le connessioni al server, questi 
componenti possono anche essere utilizzati per chiamare i metodi dell'interfaccia 
dell'application server. 
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Connessione al server 

Per individuare e collegarsi all'application server, prima e necessario impostare le 
proprieta del componente connection per identificare l'application server. Questo 
processo viene descritto nella sezione "Connessione all'application server" a 
pagina 29-24. Prima di aprire la connessione, tutti i dataset client che usano il 
componente connection per comunicare con Y application server dovranno indicare 
questo fatto impostando la loro proprieta RemoteServer per specificare il componente 
connection. 

La connessione viene aperta automaticamente quando i dataset client tentano di 
accedere all' application server. Per esempio, l'impostazione della proprieta Active 
del dataset client a true apre la connessione, sempre che la proprieta RemoteServer sia 
stata impostata. 

Se non si collegano i dataset client al componente connection, e possibile aprire la 
connessione impostando la proprieta Connected del componente connection a true. 

Prima di stabilire una connessione a un application server, il componente connection 
genera un evento BeforeConnect. E possibile eseguire delle azione specifiche per 
collegare un gestore BeforeConnect tramite programma. Dopo aver stabilito la 
connessione, il componente connection genera un evento AfterConnect per tutte le 
azioni speciali. 

Abbandono o modifica di una connessione a un server 

Un componente connection abbandona una connessione all'application server 
quando 

• Si imposta la proprieta Connected a false. 

• Si libera il componente connection. Un oggetto connection viene liberato 
automaticamente quando un utente chiude l'applicazione client. 

• Si modifica una delle proprieta che identificano l'application server (ServerName, 
ServerGUID, ComputerName, e cosi via). La modifica di queste proprieta consente 
di passare, in fase di esecuzione, da un application server disponibile all'altro. II 
componente connection abbandona la connessione attiva e ne stabilisce una 
nuova. 

Anziche ricorrere a un singolo componente connection per passare da un application 
server disponibile all'altro, un'applicazione client pud utilizzare piu componenti 
connection, ciascuno dei quali e collegato a un application server differente. 

Prima di abbandonare una connessione, il componente connection chiama 
automaticamente il suo gestore di evento BeforeDisconnect, se ne e stato fornito uno. 
Se si vuole eseguire una qualsiasi particolare azione prima di annullare la 
connessione, scrivere un gestore BeforeDisconnect. Analogamente, dopo aver 
abbandonato la connessione, viene chiamato il gestore di evento AfterDisconnect. Se si 
vuole eseguire una qualsiasi particolare azione dopo aver annullato la connessione, 
scrivere un gestore AfterDisconnect. 
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Chiamata delle interfacce del server 



Non e necessario che le applicazioni chiamino direttamente l'interfaccia IAppServer 
perche le chiamate opportune vengono generate automaticamente quando si usano 
le proprieta e i metodi del dataset client. Tuttavia, benche non sia necessario operare 
direttamente con l'interfaccia IAppServer, all'interfaccia dell'application server 
potrebbero essere state aggiunte delle estensioni personalizzate se non si sta 
utilizzando SOAP. Quando si estende l'interfaccia dell'application server, e 
necessario disporre di un modo per chiamare queste estensioni usando la 
connessione creata dal componente connection. E possibile compiere questa 
operazione usando la proprieta AppServer del componente connection. Per ulteriori 
informazioni sull'estensione dell'interfaccia dell'application server, consultare 
"Estensione dell'interfaccia dell'application server" a pagina 29-17. 

AppServer e un tipo Variant che rappresenta l'interfaccia dell'application server. Per 
chiamare questa interfaccia, e necessario ottenere da questo Variant un'interfaccia 
dispatch. L'interfaccia dispatch ha lo stesso nome dell'interfaccia creata al momento 
della creazione del modulo dati remoto, a cui viene aggiunto la stringa "Disp". 
Pertanto, se il modulo dati remoto si chiama My AppServer, e possibile utilizzare 
AppServer per chiamarne la sua interfaccia nel seguente modo: 

IDispatch* disp = (IDispatch*) (MyConnection->AppServer) 
IMyAppServerDisp Templnterf ace ( (IMyAppServer*)disp) ; 
Templnterface. SpecialMethod(x,y ) ; 

L'interfaccia dispatch e dichiarata nel file _TLB.h generato dal Type Library editor. 

Se si sta utilizzando SOAP, non e possibile usare la proprieta AppServer. E necessario 
invece utilizzare un oggetto interfacciato in remoto (THTTPRio) ed effettuare 
chiamate con binding anticipate Come con tutte le chiamate con binding anticipato, 
l'applicazione client deve conoscere la dichiarazione dell'interfaccia dell'application 
server al momento della compilazione. E possibile aggiungere cio all'applicazione 
client referenziando un documento WSDL che descrive l'interfaccia che si desidera 
chiamare. Notare che nel caso dei server SOAP, questa interfaccia e completamente 
separata dall'interfaccia del modulo dati SOAP. Per informazioni sull'importazione 
di un documento WSDL che descrive l'interfaccia del server, vedere "Importazione 
di documenti WSDL" a pagina 36-17. 

La unit che dichiara l'interfaccia del server deve registrarla anche con il registro delle 
chiamata. Per i dettagli su come registrare le interfacce richiamabili, vedere "Le 
interfacce richiamabili" a pagina 36-2. 

Una volta che si e importato un documento WSDL per generare una unit che dichiara 
e registra l'interfaccia, creare un'istanza di THTTPRio per l'interfaccia desiderata: 

THTTPRio *X = new THTTPRio (NULL) ; 

Quindi, assegnare all'oggetto interfacciato in remoto YURL utilizzato dal 
componente connection, aggiungendo il nome dell'interfaccia che si desidera 
chiamare: 

X->URL = SoapConnectionl.URL + "IMylnterface" ; 



Creazione di applicazioni multi-tier 29-29 



Creazione d el I'appl i cazio ne client 

Ora, e possibile utilizzare il metodo Querylnterface per ottenere un'interfaccia per 
chiamare i metodi del server: 

Interf aceVariable = X->QueryInterface(IMyInterfaceIntf ) ; 

if (interfaceVariable) 

{ 

Interf aceVariable->SpecialMethod( a, b) ; 

} 

Notare che la chiamata a Querylnterface accetta come argomento per l'interfaccia 
richiamabile il wrapper Delphilnterface invece della stessa interfaccia richiamabile. 

Connessione a un application server che utilizza piu moduli dati 



Se un' application server basato su COM utilizza un modulo dati remoto "genitore" 
principale e numerosi moduli dati remoti figlio, come descritto in "Uso di piu moduli 
dati remoti" a pagina 29-21, e necessario utilizzare un componente connection 
separato per ogni modulo dati remoto sull'application server. Ogni componente 
connection rappresenta la connessione a un singolo modulo dati remoto. 

Benche sia possibile che l'applicazione client stabilisca connessioni indipendenti con 
ciascun modulo dati remoto sull'application server, risulta piu efficiente utilizzare 
una singola connessione all'application server condivisa pero da tutti i componenti 
connection. Vale a dire, si aggiunge un singolo componente connection che si collega 
al modulo dati remoto "principale" sull'application server e quindi, per ogni modulo 
dati remoto "figlio", si aggiunge un ulteriore componente che condivide la 
connessione al modulo dati remoto principale. 

1 Per la connessione al modulo dati remoto principale, aggiungere e configurare un 
componente connection come descritto in "Connessione all'application server" a 
pagina 29-24. L'unica limitazione e che e impossibile utilizzare una connessione 
SOAP. 

2 Per ogni modulo dati remoto figlio, utilizzare un componente TSharedConnection. 

• Impostare la sua proprieta ParentConnection al componente connection incluso 
passo 1. II componente TSharedConnection condivide la connessione che questa 
connessione principale stabilisce. 

• Impostare la sua proprieta ChildName al nome della proprieta sull'interfaccia 
del modulo dati remoto principale che espone l'interfaccia del modulo dati 
remoto figlio chiesto. 

Quando si assegna il componente TSharedConnection messo nel passo 2 come il valore 
un dataset client e proprieta RemoteServer, essa lavori come se si utilizzava una 
connessione completamente indipendente al modulo dati remoto figlio. Tuttavia, il 
componente TSharedConnection utilizza la connessione stabilita dal componente 
messo nel passo 1. 
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Scrittura di applicazioni client basate su Web 



Se si vogliono creare client basati su Web per un'applicazione database multi-tier, si 
deve sostituire il tier client con una speciale applicazioni Web che agisca 
simultaneamente sia come un client dell'application server sia come un'applicazione 
Web server installata con un server web sulla stessa macchina. Questa architettura e 
illustrata nella Figura 29.1. 

Figura 29.1 Applicazione database multi-tier basata su Web 
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La generazione dell'applicazione Web puo essere affrontata in due modi: 

• L'architettura database multi-tier puo essere abbinata alia scheda ActiveX per 
distribuire un'applicazione client come controllo ActiveX. In questo modo, 
qualsiasi browser che supporta ActiveX e in grado di eseguire l'applicazione client 
come server in-process. 

• Si possono utilizzare i pacchetti dati XML per generare un'applicazione 
InternetExpress. In questo modo si consente ai browser che supportano javascript 
di interagire con l'applicazione client tramite pagine html. 

Queste due metodologie sono molto diverse. La scelta deve essere effettuata in base 
alle considerazioni seguenti: 

• Entrambi i metodi utilizzano una diversa tecnologia (ActiveX rispetto a javascript 
e XML). Analizzare attentamente quali sistemi saranno utilizzati dagli utenti finali 
utilizzeranno. II primo metodo richiede un browser che supporti ActiveX (il che 
limita i client all'uso dei una piattaforma Windows). II secondo metodo richiede 
un browser che supporti javascript e le capacita DHTML introdotte da Netscape 4 
e Internet Explorer 4. 

• I controlli ActiveX devono essere scaricati nel browser per poter agire come server 
in-process. Da cio ne consegue che i client che utilizzeranno il metodo ActiveX 
avranno bisogno di piu memoria rispetto ai client di un'applicazione basata su 
html. 

• II metodo InternetExpress puo essere integrato con altre pagine HTML. Un client 
ActiveX deve essere eseguito in una finestra separata. 

• II metodo InternetExpress utilizza lo standard HTTP, evitando in questo modo 
qualsiasi problema di firewall rispetto a un'applicazione ActiveX. 
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• II metodo ActiveX offre una maggior flessibilita per cio che concerne la 

programmazione dell'applicazione. Non si e limitati dalle capacita delle librerie 
javascript. I dataset client utilizzati con il metodo ActiveX mettono a disposizione 
funzionalita piu estese (come filtri, intervalli, aggregazione, parametri facoltativi, 
recupero differito di BLOB, campi detail annidati, e cosi via) rispetto ai broker 
XML utilizzati con il metodo InternetExpress. 

L'aspetto e il comportamento dell'applicazione client Web potrebbero essere 
differenti se l'applicazione viene utilizzata con browser differenti. E bene collaudare 
l'applicazione con quei browser che si prevede saranno utilizzati dagli utenti finali. 



Distribuzione di un'applicazione client come controllo ActiveX 



L'architettura database multi-tiered puo essere abbinata a funzioni ActiveX per 
distribuire un'applicazione client sotto forma di controllo ActiveX. 

Quando si distribuisce un'applicazione client come controllo ActiveX, viene creato 
l'application server come per qualsiasi altra applicazione multi-tier. Per informazioni 
dettagliate sulla creazione deU'application server, consultare "Creazione 
dell'application server" a pagina 29-12. 

Quando si crea l'applicazione client, si deve usare come base una scheda Active Form 
al posto di una scheda ordinaria. Per informazioni dettagliate, consultare "Creazione 
di una Active Form per l'applicazione client". 

Dopo aver costruito e distribuito l'applicazione client, e possibile accedervi da 
qualsiasi browser Web abilitato per ActiveX su un'altra macchina. Perche un browser 
Web lanci con successo l'applicazione client, il server Web deve essere in esecuzione 
sulla macchina che ha l'applicazione client. 

Se l'applicazione client usa DCOM per le comunicazioni tra l'applicazione client e 
l'application server, la macchina con il browser Web deve essere in grado di lavorare 
con DCOM. Se la macchina con il browser Web e una macchina Windows 95, occorre 
avere installato DCOM95, che e disponibile tramite Microsoft. 

Creazione di una Active Form per l'applicazione client 

1 Poiche l'applicazione client verra distribuita come controllo ActiveX, occorre avere 
un server Web che venga eseguito sullo stesso sistema dell'applicazione client. E 
possibile usare un server gia pronto come Personal Web di Microsoft o scriverne 
uno proprio usando i componenti socket descritti nel Capitolo 37, "Operazioni con 
i socket". 

2 Creare l'applicazione client seguendo le operazioni descritte nel paragrafo 
"Creazione dell'applicazione client" a pagina 29-23, iniziando, pero, dalla 
selezione di File I New I ActiveX I Active Form, invece di iniziare un normale 
progetto client. 

3 Se l'applicazione client usa un modulo dati, aggiungere una chiamata per crearlo 
esplicitamente nell'inizializzazione della scheda attiva. 
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4 Quando l'applicazione client ha terminate compilare il progetto e selezionare 
Project I Web Deployment Options. Nella finestra di dialogo Web Deployment 
Options, occorre eseguire le seguenti operazioni: 

1 Nella pagina Project specificare la directory di destinazione, l'URL per la 
directory di destinazione e la directory HTML. Normalmente, la directory di 
destinazione e la directory HTML coincideranno con quella dei progetti per il 
server Web. L'URL di destinazione e solitamente il nome della macchina server. 

2 Nella pagina Additional Files includere midas.dll con l'applicazione client. 

5 Infine, selezionare Project I WebDeploy per distribuire l'applicazione client come 
una scheda Active. 

Qualsiasi browser Web che pud eseguire schede Active pud eseguire l'applicazione 
client specificando il file .HTM che e stato creato quando e stata distribuita 
l'applicazione client. Questo file .HTM ha lo stesso nome del progetto 
dell'applicazione client, e appare nella directory specificata come directory di 
destinazione. 

Creazione di applicazioni Web con InternetExpress 



Un'applicazione client pud richiedere che l'application server fornisca pacchetti dati 
codificati in XML invece che come Ole Variants. Combinando i pacchetti dati 
codificati in XML, speciali librerie javascript di funzioni database e il supporto per le 
applicazioni Web server, e possibile creare applicazioni thin client a cui si puo 
accedere utilizzando un browser Web che supporta javascript. Questa combinazione 
di funzionalita e detta InternetExpress. 

Prima di creare un'applicazione InternetExpress, e bene che sia chiara l'architettura 
delle applicazione Web server. Questa architettura e descritta nel Capitolo 32, 
"Creazione di applicazioni server per Internet". 

Un'applicazione InternetExpress amplia l'architettura di base di un'applicazione per 
Web server in modo che agisca come il client di un application server. Le applicazioni 
InternetExpress generano pagine HTML che contengono un misto di HTML, XML e 
javascript. HTML pilota il layout e l'aspetto delle pagine viste dagli utenti finali nel 
loro browser. XML codifica i pacchetti dati e i pacchetti delta che rappresentano le 
informazioni del database. Javascript consente ai controlli HTML di interpretare e 
trattare i dati contenuti in questi pacchetti dati XML sulla macchina client. 

Se l'applicazione InternetExpress utilizza DCOM per effettuare la connessone 
all'application server, si devono compiere altre operazioni per assicurarsi che 
l'application server garantisca ai propri client l'accesso e i permessi di esecuzione. 
Per maggiori informazioni, consultare "Concessione dei permessi per l'accesso e 
l'avvio dell'application server" a pagina 29-35. 

E possibile creare applicazioni InternetExpress per fornire ai Web browsers dati "dal 
vivo"anche se non si possiede un application server. E sufficiente aggiungere al 
modulo web il provider e il dataset associato. 
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Creazione di un'applicazione InternetExpress 



Le operazioni seguenti descrivono un modo per costruire un'applicazione Web 
utilizzando InternetExpress. II risultato e un'applicazione che crea pagine HTML che 
consentono agli utenti di interagire con i dati di un application server mediante un 
browser Web che supporta javascript. E possibile anche costruire un'applicazione 
InternetExpress utilizzando l'architettura Site Express utilizzando il produttore di 
pagine di InternetExpress (TInetXPageProducer). 

1 Scegliere File I New I Other per visualizzare la finestra di dialogo New Items, e 
sulla pagina New scegliere Web server application. Questo processo e descritto in 
"Creazione di applicazioni per Web server con Web Broker" a pagina 33-1. 

2 Dalla pagina DataSnap della Component palette, aggiungere un componente 
connection al modulo web che appare quando si crea una nuova applicazione Web 
server. II tipo di componente connessione che si aggiunge dipende dal protocollo 
di comunicazione che si vuole utilizzare. Per i dettagli, consultare la sezione 
"Scelta di un protocollo di connessione" a pagina 29-9. 

3 Impostare le proprieta del componente connessione in modo da specificare 
l'application server con cui si dovrebbe istituire una connessione. Per ulteriori 
informazioni sulla configurazione dei componenti connessione, consultare la 
sezione "Connessione all'application server" a pagina 29-24. 

4 Invece di un dataset client, dalla pagina InternetExpress della Component Palette 
aggiungere al modulo web un broker XML. Come TClientDataSet , TXMLBroker 
rappresenta i dati forniti da un provider sull'application server e interagisce con 
l'application server tramite la sua interfaccia IAppServer. Comunque, a differenza 
dei dataset client, i broker XML richiedono i pacchetti dati sotto forma di XML 
invece che come Ole Variants, e interagiscono con componenti InternetExpress 
invece che con i controlli per dati. 

5 Impostare la proprieta RemoteServer del broker XML in modo che punti al 
componente connection aggiunto al punto 2. Impostare la proprieta ProviderName 
in modo da indicare il provider sull'application server che fornisce i dati e applica 
gli aggiornamenti. Per maggiori informazioni sulla configurazione dei broker 
XML, consultare la sezione "Uso di un broker XML" a pagina 29-36. 

6 Aggiungere al modulo web un produttore di pagine InternetExpress 
(TInetXPageProducer) per ogni singola pagina che gli utenti vedranno nel loro 
browser. Per ogni produttore di pagine, si dovra impostare la proprieta 
IncludePathURL per indicare dove trovare le librerie javascript che introdurranno 
nei controlli HTML generati le funzionalita per la gestione dei dati. 

7 Fare clic-destro su una pagina Web e scegliere il comando Action Editor per 
visualizzare l'Action editor. Aggiungere un elemento di azione per ogni 
messaggio che si desidera gestire dal browser. Associare i produttori di pagine 
aggiunti al passo 6 con queste azioni, impostandone la proprieta Producer o 
scrivendo del codice in un gestore di evento On Action. Per maggiori informazioni 
sull'aggiunta di elementi di azione utilizzando l'Action editor, consultare la 
sezione "Aggiunta di azioni al dispatcher" a pagina 33-5. 
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8 Fare doppio clic su ogni pagina Web per visualizzare il Web page editor. (Si pud 
attivare l'editor anche facendo clic nell'Object Inspector sul pulsante ellissi accanto 
alia proprieta WebPageltems). In questo editor e possibile aggiungere tutti gli 
elementi Web in modo, progettando cosi tutte le pagine che gli utenti vedranno 
nel proprio browser. Per maggiori informazioni sulla progettazione di pagine Web 
per l'applicazione InternetExpress, consultare la sezione "Creazione di pagine 
web con produttori di pagine InternetExpress" a pagina 29-39. 

9 Generare l'applicazione Web. Una volta installata questa applicazione sul server 
web, i browser la potranno richiamare specificando, come parte ScriptName 
dell'URL, il nome dell'applicazione e, come parte Pathinfo, il nome del 
componente Web Page. 

Uso delle librerie javascript 

Le pagine HTML generate dai componenti InternetExpress e gli elementi Web che 
esse contengono fanno uso di varie librerie javascript fornite nella directory source/ 
webmidas: 



Tabella 29.3 Librerie javascript 
Libreria Descrizione 

xmldom.js Questa libreria e un parser XML compatibile con DOM scritto in javascript. 

Consente ai parser che non supportano XML di utilizzare i pacchetti dati XML. 
Si noti che non include il supporto per XML Islands, che sono supportati da 
IE5 e dalle versioni successive. 

xmldb.js Questa libreria definisce classi di accesso ai dati che gestisce i pacchetti dati 

XML e i pacchetti delta XML. 

xmldisp.js Questa libreria definisce classi che associano le classi di accesso ai dati in 

xmldb con i controlli HTML nella pagina HTML. 

xmlerrdisp.js Questa libreria definisce classi che possono essere utilizzate durante la 

riconciliazione degli errori di aggiornamento. Queste classi non sono utilizzate 
da nessuno dei componenti interni InternetExpress, ma risultano utili quando 
si scrivera un produttore di riconciliazione. 

xmlshow.js Questa libreria include funzioni per visualizzare pacchetti dati XML e 

pacchetti delta XML formattati. Questa libreria non e utilizzata da nessun 
componente InternetExpress, ma e utile in fase di debug. 



Una volta installate queste librerie, si deve impostare la proprieta IncludePathURL di 
tutti i produttori di pagine InternetExpress per indicare dove e possibile reperirle. 

E possibile scrivere le proprie pagine HTML utilizzando le classi javascript fornite in 
queste librerie invece di utilizzare elementi Web per generare le pagine Web. 
Comunque, occorre essere certi che il codice scritto non faccia niente di illegale, in 
quanto queste classi includono un ridotto controllo sugli errori (per ridurre al 
minimo la dimensione delle pagine Web generate). 

Concessione dei permessi per I'accesso e I'awio dell'application server 

Le richieste provenienti dalle applicazioni InternetExpress appaiono all'application 
server come se fossero originate da un account guest di nome IUSR_computername, 
dove computername e il nome del sistema che esegue l'applicazione Web. Per 
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impostazione predefinita, questo account non gode dei per messi per accedere o 
avviare l'application server. Se si cerca di utilizzare l'applicazione Web senza 
concedere questi permessi, nel momento in cui il browser Web tenta di caricare la 
pagina viene generate un errore EOLE_ACCESS_ERROR. 

Poiche l'application server viene eseguito in questo account guest, non puo essere 
disattivato dagli altri account. 

Per accordare all'applicazione Web i permessi di accesso e di awio, eseguire 
DCOMCnfg.exe, ubicato nella directory System32 della macchina che esegue 
l'application server. Le istruzioni seguenti descrivono come configurare l'application 
server: 

1 Quando si esegue DCOMCnfg, selezionare l'application server nell'elenco delle 
applicazioni sulla pagina Applications. 

2 Fare clic sul pulsante Properties. Non appena la finestra di dialogo cambia, 
selezionare la pagina Security. 

3 Selezionare Use Custom Access Permissions, e premere il pulsante Edit. 
Aggiungere il nome IUSR_computername all'elenco degli account con permesso 
di accesso, dove computername e il nome della macchina che esegue 
l'applicazione Web. 

4 Selezionare Use Custom Launch Permissions, e premere il pulsante Edit. 
Aggiungere IUSR_computername anche a questo elenco. 

5 Fare clic sul pulsante Apply. 

Uso di un broker XML 



II broker XML assolve due funzioni principali: 

• Recupera i pacchetti dati XML dall'application server e li rende disponibili agli 
elementi Web che generano il codice HTML dell'applicazione InternetExpress. 

• Riceve dai browser gli aggiornamenti sotto forma di pacchetti delta XML e li 
applica all'application server. 

Recupero di pacchetti dati XML 

Prima che il broker XML possa fornire i pacchetti dati XML ai componenti che 
generano le pagine HTML, deve recuperarli dall'application server. A questo scopo 
utilizza l'interfaccia IAppServer che acquisisce tramite un componente connessione. 

Anche quando si utilizza SOAP, in cui l'application server supporta IAppServerSOAP, 
il broker XML utilizza IAppServer perche il componente connection agisce come un 
adattatore tra le due interfacce. 

Per fare in modo che il produttore XML possa utilizzare l'interfaccia IAppServer, si 
devono impostare le seguenti proprieta: 

• Impostare la proprieta RemoteServer al componente connessione che istituisce la 
connessione con l'application server e ottiene la sua interfaccia IAppServer. In fase 
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di progettazione, si puo selezionare questo valore da un elenco a discesa 
nell'Object Inspector. 

• Impostare la proprieta ProviderName al nome del componente provider 
sull'application server che rappresenta il dataset da cui si vogliono i pacchetti dati 
XML. Questo provider provvede a fornire i pacchetti dati XML e ad applicare gli 
aggiornamenti dai pacchetti delta XML. In fase di progettazione, se la proprieta 
RemoteServer e impostata e il componente connessione ha una connessione attiva, 
l'Object Inspector visualizza un elenco di provider disponibili. (Se si sta 
utilizzando una connessione DCOM l'application server deve essere registrato 
anche sulla macchina client). 

Due proprieta consentono di indicare cio che si desidera includere nei pacchetti dati: 

• E possibile limitare il numero di record che vengono aggiunti al pacchetto dati 
impostando la proprieta MaxRecords. Cio risulta particolarmente importante per 
important dataset estesi in quanto le applicazioni InternetExpress inviano l'intero 
pacchetto dati ai browser client. Se il pacchetto dati e troppo grande, il tempo 
necessario per scaricare i dati potrebbe diventare proibitivamente lungo. 

• Se il provider sull'application server rappresenta una query o una procedura 
registrata, si potrebbero fornire valori di parametro prima di ottenere un pacchetto 
dati XML. Questi valori di parametro possono essere forniti mediante la proprieta 

Params. 

I componenti che generano HTML e javascript per l'applicazione di InternetExpress, 
una volta impostata la loro proprieta XMLBroker, usano automaticamente il 
pacchetto dati XML del broker XML. Per ottenere direttamente il pacchetto dati XML 
nel codice, utilizzare il metodo RequestRecords. 

Quando il broker XML fornisce un pacchetto dati a un altro componente (o si chiama 
il metodo RequestRecords), il broker riceve un evento OnRequestRecords. Si puo 
utilizzare questo evento per fornire una propria stringa XML invece del pacchetto 
dati ottenuto dall'application server. Per esempio, si potrebbe recuperare il pacchetto 
dati XML dall'application server utilizzando GetXMLRecords, e quindi modificare il 
pacchetto prima di passarlo alia successiva pagina Web. 

Applicazione degli aggiornamenti da pacchetti delta XML 

Quando si aggiunge il broker XML al modulo web (o a un modulo dati contenente un 
TWebDispatcher), esso si registra automaticamente presso il dispatcher Web come un 
oggetto con dispatch automatico. Cio significa che, a differenza di altri componenti, 
non e necessario creare un elemento di azione per il broker XML per far si che sia in 
grado di rispondere ai messaggi di aggiornamento provenienti da un browser Web. 
Questi messaggi contengono pacchetti delta XML che dovrebbero essere applicati 
all'application server. Tipicamente, sono generati da un pulsante appositamente 
creato in una delle pagine HTML prodotte dall'applicazione client Web. 

Affinche il dispatcher sia in grado di riconoscere i messaggi per il broker XML, e 
necessario descriverli utilizzando la proprieta WebDispatch. Impostare la proprieta 
Pathlnfo alia sezione "percorso" dell'URL a cui vengono trasmessi i messaggi per il 
broker XML. Impostare MethodType al valore dell'header del metodo dei messaggi di 
aggiornamento indirizzati a quell'URL (di solito mtPost). Se si vuole rispondere a 
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tutti i messaggi aventi il percorso specificato, impostare MethodType a mtAny. Se non 
si vuole che il broker XML risponda direttamente ai messaggi di aggiornamento (per 
esempio, nel caso li si voglia gestire esplicitamente utilizzando un elemento di 
azione), impostare la proprieta Enabled a false. Per maggiori informazioni su come fa 
il dispatcher Web a determinare il componente che gestira i messaggi provenienti dal 
browser Web, consultare la sezione "Dispatch dei messaggi di richiesta" a 
pagina 33-5. 

Quando il dispatcher passa un messaggio di aggiornamento al broker XML, passa gli 
aggiornamenti all'application server e, se si verificano errori di aggiornamento, 
riceve un pacchetto delta XML che descrive tutti gli errori di aggiornamento. Infine, 
ritrasmette al browser un messaggio di risposta che puo sia indirizzare di nuovo il 
browser alia stessa pagina che aveva generato il pacchetto delta XML, sia 
trasmettergli nuovi contenuti. 

Esistono diversi eventi che consentono di inserire elaborazione personalizzate in 
tutte queste fasi del processo di aggiornamento: 

1 Quando il dispatcher passa per la prima volta il messaggio di aggiornamento al 
broker XML, riceve un evento BeforeDispatch, in cui e possibile preelaborare la 
richiesta o anche gestirla completamente. Questo evento consente al broker XML 
di gestire messaggi diversi da quelli di aggiornamento. 

2 Se il gestore di evento BeforeDispatch non gestisce il messaggio, il broker XML 
riceve un evento OnRequestUpdate, in cui e possibile applicare gli aggiornamenti 
personalmente invece di utilizzare l'elaborazione predefinita. 

3 Se il gestore di evento OnRequestUpdate non gestisce la richiesta, il broker XML 
applica gli aggiornamenti e riceve un pacchetto delta che contiene tutti gli errori di 
aggiornamento . 

4 Se non si verificano errori di aggiornamento, il broker XML riceve un evento 
OnGetResponse, in cui e possibile creare un messaggio di risposta che indica che gli 
aggiornamenti sono stati applicati con successo oppure trasmettere al browser i 
dati aggiornati. Se il gestore di evento OnGetResponse non completa la risposta 
(non imposta il parametro Handled a true), il broker XML trasmette una risposta 
che dirige di nuovo il browser al documento che aveva generato il pacchetto delta. 

5 Se si verificano errori di aggiornamento, il broker XML riceve invece un evento 
OnGetErr or Response. E possibile utilizzare questo evento per tentare di risolvere gli 
errori di aggiornamento oppure per generare una pagina Web che li descriva 
all'utente. Se il gestore di evento OnGetErrorResponse non completa la risposta 
(non imposta il parametro di died a true), il broker XML chiama uno speciale 
produttore di contenuti, di nome ReconcileProducer, per generare il contenuto del 
messaggio di risposta. 

6 Infine, il broker XML riceve un evento AfterDispatch, in cui e possibile compiere 
eventuali operazioni finali prima di ritrasmettere una risposta al browser Web. 
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Creazione di pagine web con produttori di pagine InternetExpress 



Ogni produttore di pagine InternetExpress genera un documento HTML che appare 
nel browser dei client dell'applicazione. Se l'applicazione include diversi documenti 
Web distinti, utilizzare per ognuna di esse un diverso produttore di pagine. 

II produttore di pagina InternetExpress (TInetXPageProducer) e uno speciale 
componente produttore di pagine. Come gli altri produttori di pagine, e possibile 
assegnarlo alia proprieta Producer di un elemento di azione, oppure lo puo chiamare 
esplicitamente da un gestore di evento OnAction. Per maggiori informazioni 
sull'utilizzo di produttori di contenuti con elementi di azione, consultare la sezione 
"Risposta a messaggi di richiesta mediante elementi di azione" a pagina 33-8. Per 
maggiori informazioni sui produttori di pagine, consultare la sezione "Utilizzo di 
componenti produttori di pagine" a pagina 33-14. 

II produttore di pagine InternetExpress ha, come valore della proprieta di HTMLDoc, 
un modello predefinito. Questo modello contiene una serie di marcatori, trasparenti 
per HTML, che il produttore di pagine InternetExpress utilizza per assemblare un 
documento HTML (che incorpora javascript e XML) includendo i contenuti prodotti 
da altri componenti. Prima che esso possa tradurre tutti i marcatori trasparenti per 
HTML e assemblare questo documento, e necessario indicare l'ubicazione delle 
librerie javascript utilizzate per il codice javascript incorporato nella pagina. Questa 
posizione viene specificata impostando la proprieta IncludePathURL. 

E possibile specificare i componenti che generano parti della pagina Web utilizzando 
il Web page editor. Visualizzare il Web page editor facendo doppio clic sul 
componente Web page oppure facendo clic sul pulsante ellissi accanto alia proprieta 
WebPageltems nell'Object Inspector. 

I componenti aggiunti nel Web page editor generano il codice HTML che sostituisce 
uno dei marcatori trasparenti per HTML inclusi nel modello predefinito del 
produttore di pagine InternetExpress. Questi componenti diventano il valore della 
proprieta WebPageltems. Dopo avere aggiunto i componenti nell'ordine voluto, e 
possibile personalizzare il modello aggiungendo del codice HTML o modificando i 
marcatori predefiniti. 

Utilizzo di Web page editor 

Web page editor permette di aggiungere elementi Web al produttore di pagine 
InternetExpress e di vedere la pagina HTML risultante. Visualizzare il Web page 
editor facendo doppio clic su un componente produttore di pagine InternetExpress. 

Per utilizzare Web page editor, e necessario installare Internet Explorer 4 o una 
versione successiva. 

La zona superiore del Web page editor visualizza gli elementi Web che generano il 
documento HTML. Questi elementi Web sono annidati, e in particolare ogni tipo di 
elemento Web assembla il codice HTML generato dai propri sottoelementi. Tipi 
diversi di elementi possono contenere sottoelementi differenti. Sulla sinistra, una 
struttura ad albero visualizza tutti degli elementi Web, indicando come sono 
annidati. Sulla destra, si possono vedere gli elementi Web inclusi dall'elemento al 
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momento selezionato. Se si seleziona un componente nella parte superiore del Web 
page editor, e possibile impostarne le proprieta utilizzando l'Object Inspector. 

Fare clic sul pulsante New Item per aggiungere un sottoelemento aU'elemento 
attualmente selezionato. La finestra di dialogo Add Web Component elenca solo 
quegli elementi che possono essere aggiunti aU'elemento attualmente selezionato. 

II produttore di pagine InternetExpress puo contenere un solo tipo di elemento, dei 
due possibili, ognuno dei quali genera una scheda HTML: 

• TDataForm, che genera una scheda HTML per visualizzare dati e i controlli che 
trattano tali dati o che trasmettono gli aggiornamenti. 

Gli elementi che si aggiungono a TDataForm visualizzano i dati in una griglia 
multi-record (TDataGrid) o in una serie di controlli, ognuno dei quali rappresenta 
un singolo campo di un singolo record (TFieldGroup). Inoltre, e possibile 
aggiungere una serie di pulsanti per spostarsi tra i dati o per trasmette gli 
aggiornamenti, (TDataNavigator), o un pulsante per applicare gli aggiornamenti al 
client Web (TApplyUpdatesButton). Ognuno di questi elementi contiene dei 
sottoelementi per rappresentare singoli campi o pulsanti. Infine, come con la 
maggior parte degli elementi Web, e possibile aggiungere una griglia di layout, 
(TLayoutGroup), che permette di personalizzare il layout di tutti gli elementi in 
essa contenuti. 

• TQueryForm, che genera una scheda HTML per visualizzare o leggere i valori 
definiti dall'applicazione. Per esempio, si puo utilizzare questa scheda per 
visualizzare e trasmettere i valori dei parametri. 

Gli elementi che si aggiungono a TQueryForm visualizzano i valori definiti 
dall'applicazione (T Query FieldGroup) o una serie di pulsanti per trasmettere o 
azzerare quei valori (TQuery Buttons). Ognuno di questi elementi contiene dei 
sottoelementi per rappresentare singoli valori o pulsanti. Anche ad una scheda di 
interrogazione, e possibile aggiungere una griglia di layout, esattamente come per 
le schede per dati. 

La parte inferiore del Web page editor visualizza il codice HTML generato e permette 
di vederne l'aspetto finale come in un browser (IE4). 

Impostazione delle proprieta degli elementi Web 

Gli elementi Web che si aggiungono utilizzando il Web page editor sono componenti 
specializzati che generano HTML. Ogni classe di elemento Web e stata progettata di 
produrre un determinate controllo o sezione del documento HTML finale, ma una 
serie comune di proprieta influenza l'aspetto dell'HTML finale. 

Quando un elemento Web rappresenta le informazioni di un pacchetto dati XML (per 
esempio, quando genera una serie di campi o di controlli per la visualizzazione dei 
parametri o un pulsante che interviene sui dati), la proprieta XMLBroker associa 
l'elemento Web col broker XML che gestisce il pacchetto dati. Usando la proprieta 
XMLDataSetField si puo anche specificare un dataset, che e contenuto in un campo 
del dataset di quel pacchetto dati. Se l'elemento Web rappresenta un certo campo o 
un valore di parametro, l'elemento Web ha una proprieta FieldName o ParamName. 
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E possibile applicare un attributo di stile a qualsiasi elemento Web, influenzando in 
questo modo l'aspetto complessivo di tutto Y HTML generate Stili e fogli di stile 
fanno parte degli standard di HTML 4. Essi consentono a un documento HTML di 
definire una serie di attributi di visualizzazione che vengono applicati a un 
marcatore e a tutto cio che e incluso nel suo campo d'azione. Gli elementi Web ne 
consentono un uso molto flessibile: 

• II modo piu semplice per utilizzare gli stili e quello di definire direttamente un 
attributo di stile sull'elemento Web. A questo scopo, si utilizza la proprieta Style. II 
valore di Style e semplicemente la porzione di definizione dell'attributo di una 
definizione standard di stile HTML, come, ad esempio 

color: red. 

• E possibile anche definire un foglio di stile, che definisce una serie di definizioni di 
stile. Ogni definizione include sia un selettore di stile (il nome di un marcatore a 
cui viene sempre applicato lo stile oppure un nome di stile definito dall'utente) sia 
la definizione dell'attributo racchiusa tra parentesi graffe: 

H2 B {color: red} 

.MyStyle {font-family: arial; font -weight: bold; font-size: 18px } 

L'intero set di definizioni e conservata dal produttore di pagine InternetExpress 
nella sua proprieta Styles. Ogni elemento Web puo referenziare quindi gli stili con 
nomi definiti dall'utente impostando la sua proprieta StyleRule. 

• Se si sta condividendo un foglio di stile con altre applicazioni, e possibile fornire le 
definizioni di stile come valore della proprieta Styles! He del produttore di pagine 
InternetExpress invece che della proprieta Style. I singoli elementi Web faranno 
riferimento agli stili utilizzando sempre la proprieta StyleRule. 

Un'altra proprieta comune degli elementi Web e la proprieta Custom. Custom include 
una serie di opzioni che e possibile aggiungere al marcatore HTML generate HTML 
definisce una diversa serie di opzioni per ogni tipo di marcatore. II manuale Visual 
Component Library Reference riporta per la proprieta Custom di vari elementi Web 
un esempio delle possibili opzioni. Per maggiori informazioni sulle possibili opzioni, 
utilizzare un manuale di riferimento alia sintassi HTML. 

Personalizzazione del modello del produttore di pagine InternetExpress 

II modello di un produttore di pagine InternetExpress e un documento HTML che 
incorpora marcatori aggiuntivi, tradotti dinamicamente dall'applicazione. 
Inizialmente, il produttore di pagine genera un modello predefinito come valore 
della proprieta HTMLDoc. Questo modello predefinito ha il seguente aspetto 

<HTML> 
<HEAD> 
</HEAD> 
<B0DY> 

<#INCLUDES> <#STYLES> <#WARNINGS> <#F0RMS> <#SCRIPT> 

</B0DY> 

</HTML> 

I marcatori trasparenti per HTML inclusi nel modello predefinito vengono tradotti 
nel seguente modo: 
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<#INCLUDES> genera le istruzioni che includono le librerie javascript. Queste istruzioni 
assumono il seguente aspetto 

<SCRIPT language=Javascript type="text/javascript" SRC=''IncludePathURL/xmldom. js"> </SCRIPT> 
<SCRIPT language=Javascript type="text/javascript n SRC= n IncludePathURL/xmldb. js"> </SCRIPT> 
<SCRIPT language=Javascript type="text/javascript n SRC= n lncludePathURL/xmlbind.]s"> </SCRlPT> 

<#STYLES> genera le istruzioni che definiscono un foglio di stile a partire dalle 
definizioni elencate nella proprieta Style o nella proprieta StylesFile del produttore di 
pagine InternetExpress. 

<#WARNINGS> non genera nulla in fase di esecuzione. In fase di progettazione, aggiunge 
messaggi di awertimento per problemi rilevati durante la generazione del 
documento HTML. E possibile visualizzare questi messaggi nel Web page editor. 

<#F0RMS> genera il codice HTML prodotto dai componenti aggiunti nel Web page 
editor. II codice HTML prodotto da ogni componente e generato in base alia 
posizione che occupa nella sequenza di WebPageltems. 

<#SCRIPT> genera un blocco di dichiarazioni javascript che sono utilizzate nel codice 
HTML generato dai componenti aggiunti nel Web page editor. 

E possibile sostituire il modello predefinito modificando il valore di HTMLDoc 
oppure impostando la proprieta HTMLFile. II modello HTML personalizzato puo 
includere tutti i marcatori trasparenti per HTML che costituiscono il modello 
predefinito. II produttore di pagine InternetExpress tradurra automaticamente questi 
marcatori nel momento in cui si chiama il metodo Content. Inoltre, il produttore di 
pagine InternetExpress e in grado di tradurre automaticamente altri ire marcatori: 

<#BODYELEMENTS> viene sostituito dallo stesso codice HTML prodotto dai 5 marcatori 
inclusi nel modello predefinito. Risulta utile quando si genera un modello in un 
editor HTML e si desidera utilizzare il layout predefinito aggiungendo pero altri 
elementi con l'editor. 

<#C0MP0NENT Name=WebComponentName> viene sostituito dai codice HTML generato dai 
componente con nome WebComponentName. Questo componente puo essere uno dei 
componenti aggiunti nel Web page editor, o un qualsiasi altro componente purche 
supporti l'interfaccia IWebContent e abbia lo stesso Owner del produttore di pagine 
InternetExpress . 

<#DATAPACKET XMLBroker=BrokerName> viene sostituito col pacchetto dati XML ottenuto 
dai broker XML specificato con BrokerName. Quando si osserva nel Web page editor il 
codice HTML generato dai produttore di pagine InternetExpress, si vedra questo 
marcatore invece dell'effettivo pacchetto dati XML. 

Inoltre, il modello personalizzato puo includere qualsiasi altro marcatore trasparente 
per HTML definito dall'utente. Quando il produttore di pagine InternetExpress 
incontra un marcatore che non appartiene a nessuno dei sette tipi che e in grado di 
tradurre automaticamente, genera un evento OnHTMLTag in cui si potra inserire del 
codice che esegua traduzioni ad hoc. Per maggiori informazioni sui modem HTML in 
generale, consultare la sezione "Modelli HTML" a pagina 33-14. 
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I componenti che appaiono nel Web page editor generano codice statico. do significa 
che, a meno che l'application server modifichi i metadati inclusi nei pacchetti dati, il 
codice HTML e sempre lo stesso, indipendentemente da quando viene generato. E 
possibile evitare il sovraccarico di lavoro derivante dalla generazione dinamica in 
fase di esecuzione di questo codice, in risposta ad ogni messaggio di richiesta, se si 
copia il codice HTML generato nel Web page editor e lo si utilizza come modello. 
Poiche il Web page editor visualizza un marcatore <#DATAPACKET> invece 
dell'effettivo XML, l'utilizzo di questo codice come modello continua a consentire 
all'applicazione di recuperare dinamicamente i pacchetti dati dall'application server. 
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Capitolo 




UsodiXMLnelle 



applicazioni 
database 



Oltre al supporto per la connessione ai server di database, C++Builder permette di 
gestire documenti XML come se anch'essi fossero server di database. XML 
(Extensible Markup Language) e un linguaggio di markup per la descrizione di dati 
strutturati. I documenti XML dotano di un formato standard e trasportabile i dati 
utilizzati nelle applicazioni Web, nelle comunicazioni business-to-business, e cosi 
via. Per informazioni sulle possibility offerte da C++Builder per lavorare 
direttamente con i documenti XML, consultare il Capitolo 35, "Operazioni con 
documenti XML". 

Le possibility offerte da C++Builder per operare con documenti XML nelle 
applicazioni database si basano su un insieme di componenti in grado di convertire 
dei pacchetti dati (la proprieta Data di un client dataset) in documenti XML e, 
inversamente, di convertire documenti XML in pacchetti dati. Prima di utilizzare 
questi componenti, bisogna definire la trasformazione tra il documento XML e il 
pacchetto dati. Una volta definita la trasformazione, i componenti speciali si possono 



• convertire documenti XML in pacchetti dati. 

• fornire dati prelevati da un documento XML e risolvere gli aggiornamenti a un 
documento XML. 

• utilizzare un documento XML come client di un provider. 



Prima di convertire tra pacchetti dati e documenti XML, bisogna definire la relazione 
tra i metadati in un pacchetto dati e i nodi del documento XML corrispondente. La 
descrizione della relazione e registrata in uno speciale documento XML detto 
trasformazione. 



usare per 



Definizione della trasformazione 
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Definizione della trasformazione 

Ogni file di trasformazione contiene due cose: la mappatura tra i nodi di uno schema 
XML e i campi di un pacchetto dati, piu uno schema di documento XML che 
rappresenta la struttura dei risultati della trasformazione. Una trasformazione e una 
mappatura a senso unico: da uno schema o da un documento XML a un pacchetto 
dati, oppure dai metadati di un pacchetto dati a uno schema XML. Spesso, si creano 
file di trasformazione a coppie: uno che fa una mappatura da XML a pacchetto dati e 
un altro che mappa da pacchetto dati a XML. 

Per creare i file di trasformazione di una mappatura, si ricorre al programma di 
utilita XMLMapper fornito nella directory bin. 

Mappatura tra nodi XML e campi di un pacchetto dati 



XML dispone di una modalita in formato testo per memorizzare o rappresentare i 
dati strutturati. I dataset forniscono un'altra modalita per memorizzare e descrivere i 
dati strutturati. Per convertire un documento XML in un dataset, quindi, e necessario 
identificare le corrispondenze tra i nodi di un documento XML e i campi di un 
dataset. 

Si consideri, ad esempio, un documento XML che rappresenta un insieme di 
messaggi di posta elettronica. Potrebbe presentarsi cosi (con un solo messaggio): 

<?xml version=" 1. " standalone= 'yes ' ?> 
<email> 
<head> 
<from> 

<narae>Dave Boss</name> 
< addr e s s >dbo s s @My Co . c om< / addr e s s > 
</from> 
<to> 

<name>Joe Engmeer</name> 

<address>jengineer@MyCo.com</address> 
</to> 
<cc> 

<name>Robin Smith/name> 

<addres s >rsmi thgMyCo . com< /addres s > 
</cc> 
<cc> 

<name>Leonard Devon</naroe> 

<address>ldevon@MyCo.com</address> 
</cc> 
</head> 
<body> 

<subject>XML componeiits</subject> 
<content> 
Joe, 

Attached is the specification for the new XML component support in C++Builder. 
This looks like a good solution to our buisness-to-buisness application! 
Also attached, please find the project schedule. Do you think its reasonable? 
Dave. 
</content> 

<attachrnent attachf ile= "XMLSpec . txt "/> 
ottachment attachf ile= "Schedule . txt " /> 
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</body> 
</email> 

Un modo naturale di mappatura tra il documento e un dataset fa corrispondere un 
unico record a ciascun messaggio di posta elettronica. II record conterra i campi del 
nome e dell'indirizzo del mittente. Siccome i destinatari del messaggio potrebbero 
essere piu di uno, il destinatario (<to>) dovrebbe essere mappato a un dataset 
annidato. La riga <subject> potrebbe essere mappata a un campo stringa, mentre 
probabilmente il messaggio stesso (<content>) potrebbe essere un campo memo. I 
nomi dei file allegati potrebbero essere mappati a un dataset annidato perche un 
messaggio puo avere numerosi allegati. < Pertanto, il messaggio precedente potrebbe 
essere mappato a un dataset simile al seguente: 




Dave Boss dboss@MyCo.Com (DataSet) (DataSet) XML components (MEMO) (DataSet) 



in cui il dataset annidato nel campo "To" e 

Nome Indirizzo 

Joe Engineer jengineer@MyCo.Com 



il dataset annidato nel campo "CC" e 

Nome Indirizzo 

Robin Smith rsmith@MyCo.Com 
Leonard Devon ldevon@MyCo.Com 

e il dataset annidato nel campo "Attach" e 

Attachfile 

XMLSpec.txt 
Schedule.txt 

Definire questa mappatura significa identificare i nodi del documento XML che 
possono essere ripetuti e farli corrispondere con dataset annidati. Gli elementi 
provvisti di tag e che hanno un valore vengono visualizzati solo una volta (come 
<content>...</content>) corrispondono a campi il cui tipo di dato riflette il tipo di 
dati che puo venire visualizzato come valore. Gli attributi di un tag (come l'attributo 
AttachFile del tag degli allegati) sono in grado di mapparsi anche con dei campi. 

Va notato che non tutti i tag nel documento XML appaiono nel dataset 
corrispondente. Ad esempio, all'elemento <head>...<head/> non corrisponde alcun 
elemento nel dataset risultante. Di solito, solo elementi che hanno valori, elementi 
che possono essere ripetuti o gli attributi di un tag corrispondono a campi (compresi 
i campi di dataset annidati) di un dataset. L'eccezione a questa regola si ha quando 
un nodo genitore del documento XML corrisponde a un campo il cui valore e dato 
dai valori dei nodi figlio. Ad esempio, un documento XML potrebbe contenere un 
insieme di tag come 
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<FullName> 

<Title> Mr. </Title> 

<FirstName> John </FirstName> 

<LastName> Smith </LastName> 
</FullName> 

che potrebbe corrispondere a un singolo campo dataset con il valore 

Mr. John Smith 

Utilizzo di XMLMapper 



II programma di utilita di mappatura XML, xmlmapper.exe, permette di definire le 
mappature in tre modi: 

• Da uno schema XML (o documento) esistente a un dataset client che si definisce. 
Serve per creare un'applicazione di database che funzioni con dati di cui gia si ha 
uno schema XML. 

• Da un pacchetto dati esistente a un nuovo schema XML da definire. E utile quando 
si desidera esporre informazioni di database esistenti in XML, ad esempio per 
creare un nuovo sistema di comunicazione business-to-business. 

• Tra uno schema XML esistente e un pacchetto dati esistente. E utile quando si 
desidera fare funzionare insieme uno schema XML e un database che descrivono 
le stesse informazioni. 

Una volta definita la mappatura, e possibile generare i file di trasformazione che 
servono a convertire i documenti XML in pacchetti dati e, inversamente, a convertire 
i pacchetti dati in documenti XML. Notare che solo il file di trasformazione e 
direzionale: una singola mappatura serve per generare sia la trasformazione da XML 
a pacchetto dati, sia quella da pacchetto dati a XML. 

XML mapper si appoggia a due file .DLL (midas.dll e msxml.dll) per funzionare 
correttamente. Accertarsi che ambedue i file siano stati installati prima di usare 
xmlmapper.exe. Inoltre, msxml.dll deve essere registrato come COM server. Per 
registrarlo si utilizza Regsvr32.exe. 

Caricamento di uno schema XML o di un pacchetto dati 

Prima di definire una mappatura e di generare un file di trasformazione, bisogna 
caricare le descrizioni del documento XML e del pacchetto dati di cui si sta 
tracciando la mappa. 

E possibile caricare un documento o uno schema XML selezionando File I Open e poi 
il documento o lo schema nella finestra di dialogo che appare. 

E possibile caricare un pacchetto dati scegliendo File I Open e selezionando un file di 
pacchetto dati nella finestra di dialogo che appare. (il pacchetto dati e semplicemente 
il file generato quando si chiama il metodo SaveToFile di un dataset client). Se non si e 
salvato il pacchetto dati su disco, lo si puo prelevare direttamente dall'application 
server di un'applicazione multi-tier facendo clic con il pulsante destro nel riquadro 
Datapacket e scegliendo Connect To Remote Server. 



30-4 Guida alia programmazione 



Definizione della trasformazione 



E possibile caricare solo un documento o uno schema XML, solo un pacchetto dati, 
oppure caricarli entrambi. Se si carica solo un lato della mappatura, XML mapper 
puo generare una mappatura naturale dell'altro lato. 

Definizione delle mappature 

La mappatura tra un documento XML e un pacchetto dati non deve 
obbligatoriamente comprendere tutti i campi del pacchetto dati o tutti gli elementi 
dotati di tag del documento XML. Quindi, bisogna prima specificare quali elementi 
mappare. Per specificarli, selezionare prima la pagina Mapping nel riquadro centrale 
della finestra di dialogo. 

Per specificare gli elementi di un documento o di uno schema XML mappati nei 
campi di un pacchetto dati, si seleziona la pagina Document View o Schema View del 
riquadro del documento XML e si fa doppio clic sui nodi degli elementi che mappano 
nei campi del pacchetto dati. 

Specificare i campi del pacchetto dati mappati verso gli elementi o attributi etichettati 
nel documento XML e fare doppio clic sui nodi relativi ai campi nel riquadro 
Datapacket. 

Se si e solo caricato un lato della mappatura (il documento XML o il pacchetto dati), e 
possibile generare l'altro dopo avere selezionato i nodi mappati. 

• Se si genera un pacchetto dati da un documento XML, prima si definiscono gli 
attributi dei nodi selezionati, che determinano i tipi di campi a cui essi 
corrispondono nel pacchetto dati. Nel riquadro centrale, si seleziona la pagina 
Node Repository. Selezionare ogni nodo che partecipa alia mappatura e indicare 
gli attributi del campo corrispondente. Se la mappatura non e diretta (ad esempio, 
un nodo con sottonodi che corrisponde a un campo il cui valore e determinate dai 
sottonodi), spuntare la casella di controllo User Defined Translation. Sara 
necessario poi scrivere un gestore di evento per eseguire la trasformazione sui 
nodi definiti dall'utente. 

Una volta che si e specificato come devono essere mappati i nodi, scegliere 
Create I Datapacket da XML. II pacchetto dati corrispondente viene 
automaticamente generato e appare nel riquadro Datapacket. 

• Se si genera un documento XML da un pacchetto dati, scegliere Create I XML da 
Datapacket. Viene visualizzata una finestra di dialogo dove e possibile specificare 
i nomi dei tag e degli attributi nel documento XML che corrispondono a campi, a 
record e a dataset nel pacchetto dati. Per valori del campo, si specifica se, dal nome 
che gli si da, corrispondono a un elemento con tag, dotato di un valore, o a un 
attribute Nomi che iniziano con il simbolo @ mappano ad attributi del tag 
corrispondenti al record, mentre nomi che non iniziano II simbolo @ mappano a 
elementi dotati di tag che hanno valori e che sono annidati all'interno 
dell'elemento del record. 

• Se si sono caricati sia un documento XML che un pacchetto dati (file di dataset 
client), assicurarsi di selezionare i nodi corrispondenti nello stesso ordine. I nodi 
corrispondenti dovrebbero apparire l'uno accanto all'altro nella tabella all'inizio 
della pagina Mapping. 
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Una volta che si e caricato o generato sia il documento XML che il pacchetto dati e 
che si sono selezionati i nodi visualizzati nella mappatura, la tabella all'inizio della 
pagina Mapping riflette la mappatura che si e definita. 

Generazione dei file di trasformazione 

Per generare un file di trasformazione, utilizzare i seguenti passi: 

1 Per prima cosa, selezionare il pulsante di scelta indicante che cosa si ottiene dalla 
trasformazione: 

• Scegliere il pulsante Datapacket to XML se la mappatura va da pacchetto dati a 
documento XML. 

• Scegliere il pulsante XML to Datapacket se la mappatura va da documento 
XML a pacchetto dati. 

2 Se si genera un pacchetto dati, si desiderera anche utilizzare i pulsanti di scelta 
nella sezione Create Datapacket As. Questi pulsanti permettono di specificare 
come sara utilizzato il pacchetto dati: come dataset, come pacchetto delta per 
applicare aggiornamenti, come parametri da fornire a un provider prima di 
fornire i dati. 

3 Fare clic su Create e su Test Transformation per generare una versione in memoria 
della trasformazione. XML mapper mostra il documento XML che verrebbe 
generato nel riquadro Datapacket o il pacchetto dati del documento XML nel 
riquadro XML Document. 

4 Infine, scegliere File I Save I Transformation e salvare il file di trasformazione. I file 
di trasformazione sono file XML speciali (con l'estensione .xtr) che descrivono la 
trasformazione definita. 

Conversione di documenti XML in pacchetti dati 



Una volta creato un file di trasformazione indicante come trasformare un documento 
XML in un pacchetto dati, si possono creare pacchetti dati per qualsiasi documento 
XML conforme alio schema utilizzato nella trasformazione. Questi pacchetti dati 
possono quindi venire assegnati a un dataset client e salvati su un file, in modo da 
formare la base di un'applicazione per database basata su file. 

II componente TXMLTransform trasforma un documento XML in un pacchetto dati 
secondo la mappatura contenuta in un file di trasformazione. 

E possibile anche utilizzare TXMLTransform per convertire un pacchetto dati 
visualizzato in formato XML in un documento XML arbitrario. 



Specifica del documento XML di origine 



Ci sono tre modi per specificare il documento XML di origine: 

• Se il documento di origine e un file .xml su disco, e possibile utilizzare la proprieta 
SourceXmlFile. 
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• Se il documento di origine e una stringa in memoria di dati XML, e possibile 
utilizzare la proprieta SourceXml. 

• Se per il documento di origine ha un'interfaccia IDOMDocument, e possibile 
utilizzare la proprieta SourceXmlDocument. 

TXMLTransform controlla queste proprieta nell'ordine elencato. Solo se SourceXmlFile 
e una stringa vuota controlla la proprieta SourceXml. Solo se SourceXmlFile e una 
stringa vuota controlla la proprieta SourceXml. E solo se SourceXml e una stringa 
vuota controlla la proprieta SourceXmlDocument. 

Specifica della trasformazione 



Ci sono due modi per specificare la trasformazione che converte il documento XML 
in un pacchetto dati: 

• Impostare la proprieta TransformationFile per indicare un file di trasformazione che 
e stato creato utilizzando xmlmapper.exe. 

• Impostare la proprieta TransformationDocument se l'interfaccia della 
trasformazione e IDOMDocument. 

TXMLTransform controlla queste proprieta nell'ordine elencato. Cioe, prima controlla 
il nome file nella proprieta TransformationFile. Solo se TransformationFile e una stringa 
vuota controlla la proprieta TransformationDocument. 

Ottenimento del pacchetto dati risultante 



Per fare in modo che TXMLTransform esegua la sua trasformazione e generi un 
pacchetto dati, e solamente necessario leggere la proprieta Data. Ad esempio, il 
seguente codice utilizza un documento XML e un file di trasformazione per generare 
un pacchetto dati, e poi assegnarlo a un dataset client: 

XMLTransforrol->SourceXMLFile = "CustomerDocument .xml" ; 
XMLTransforml->TransformationFile = "CustXMLToCustTable.xtr" ; 
ClientDataSetl->XMLData = XMLTransforml->Data; 

Conversione dei nodi definiti dall'utente 



Quando si definisce una trasformazione utilizzando xmlmapper.exe, e possibile 
specificare che alcuni dei nodi nel documento XML sono "User-defined ". I nodi 
definiti dall'utente sono nodi di cui si desidera fornire la trasformazione in codice, 
invece di contare su una traduzione diretta valore-del-nodo-valore-del-campo. 

Utilizzando l'evento OnTranslate si puo fornire il codice per tradurre i nodi definiti 
dall'utente. OnTranslate viene chiamato ogni volta che il componente 
TXMLTransform incontra un nodo definito dall'utente nel documento XML. Nel 
gestore di evento OnTranslate, e possibile leggere il documento di origine e 
specificare il valore risultante del campo nel pacchetto dati. 

Ad esempio, il seguente gestore di evento OnTranslate converte un nodo nel 
documento XML con questo formato 
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<FullName> 

<Title> </Title> 

<FirstName> </FirstName> 

<LastName> </LastName> 
</FullName> 

in un singolo valore del campo: 

void fastcall TForml: :XMLIransformlTranslate(TObject *Sender, AnsiString Id, 

_di_lDOMNode SrcNode, AnsiString &Value, _di_lDOMNode DestNode) 

{ 

if (Id == "FullName" ) 

{ 

Value = ""; 

if ( SrcNode. hasChildNodes) 
{ 

_di_IXMLDOMNode CurNode = SrcNode. firstChild; 
Value = SrcValue + AnsiString (CurNode .nodeValue) ; 
while (CurNode != SrcNode. lastChild) 
{ 

CurNode = CurNode. nextSibling; 

Value = Value + AnsiString (" "); 

Value = Value + AnsiString (CurNode. nodeValue) ; 

} 

} 

} 

} 

Impiego di un documento XML come origine di un provider 



II componente TXMLTransformProvider permette di utilizzare un documento XML 
come se fosse una tabella di database. TXMLTransformProvider assembla i dati di un 
documento XML e gli applica gli aggiornamenti provenienti dai client. Ai client, 
come dataset client o ai broker XML appare come qualsiasi altro componente 
provider. Per informazioni sui componenti provider, consultare il Capitolo 28, "Uso 
di componenti provider". Per informazioni sull'utilizzo di componenti provider con i 
dataset client, consultare "Uso di un dataset client con un provider di dati" a 
pagina 27-26. 

Mediante la proprieta XMLDataFile e possibile specificare il documento XML che dal 
quale il provider XML fornisce dati e al quale applica gli aggiornamenti. 

I componenti TXMLTransformProvider utilizzano componenti interni TXMLTransform 
per la traduzione tra i pacchetti dati e il documento XML di origine: uno per tradurre 
il documento XML in pacchetti dati e uno per ritradurre i pacchetti dati nel formato 
XML del documento di origine dopo avere applicato gli aggiornamenti. Ai due 
componenti TXMLTransform si accede tramite le proprieta TransformRead e 
Tran sform Write, r ispettivamente . 

Quando si utilizza TXMLTransformProvider, e necessario specificare le trasformazioni 
che i due componenti TXMLTransform utilizzano per tradurre tra pacchetti dati e il 
documento XML di origine. Si fa questo impostando la proprieta TransformationFile o 
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TransformationDocument del componente TXMLTransform, proprio come quando si 
utilizza tin componente indipendente TXMLTransform. 

Inoltre, se la trasformazione comprende anche nodi definiti dall'utente, bisogna 
fornire un gestore di evento OnTranslate ai componenti interni TXMLTransform. 

Non e necessario specificare il documento di origine nei componenti TXMLTransform 
che sono i valori di TransformRead e di TransformWrite. Per TransformRead, l'origine e 
il file specificato dalla proprieta XMLDataFile del provider( benche, se si imposta 
XMLDataFile a una stringa vuota, sia possibile fornire il documento di origine 
utilizzando TransformRead.XmlSource o TransformRead-XmlSourceDocument ). Per 
TransformWrite, l'origine e generata internamente dal provider quando applica gli 
aggiornamenti. 

Utilizzo di documenti XML come client di un provider 



II componente TXMLTransformClient agisce come adattatore per consentire di usare 
un documento (o un insieme di documenti) XML come client di un application server 
remoto (o semplicemente come client di un dataset a cui si collega tramite un 
componente TDataSetProvider ). Cioe, il client TXMLTransform consente di pubblicare 
i dati di database sotto forma di documento XML e di utilizzare le richieste di 
aggiornamento (inserimenti o cancellazioni) provenienti da un'applicazione esterna 
che li fornisce sotto forma di documenti XML. 

Per specificare il provider dal quale l'oggetto TXMLTransformClient preleva i dati e al 
quale applica gli aggiornamenti, si imposta la proprieta ProviderName. Come con la 
proprieta ProviderName di un dataset client, ProviderName pud essere il nome di un 
provider su un application server remoto, oppure un provider locale con lo stesso 
formato o lo stesso modulo dati dell'oggetto TXMLTransformClient. Per informazioni 
sui provider, consultare il Capitolo 28, "Uso di componenti provider". 

Se il provider si trova su un application server remoto, e necessario utilizzare un 
componente connection DataSnap per collegarsi all'application server in questione. 
Si specifica il componente connection mediante la proprieta RemoteServer. Per 
informazioni sui componenti di connessione DataSnap, consultare "Connessione 
all'application server" a pagina 29-24. 

Prelievo di un documento XML da un provider 



TXMLTransformClient utilizza un componente interno TXMLTransform per tradurre i 
pacchetti dati forniti dal provider in un documento XML. Si accede al componente 
TXMLTransform dandogli il valore della proprieta TransformGetData. 

Prima di creare un documento XML che rappresenta i dati presi da un provider, e 
necessario specificare il file di trasformazione che TransformGetData utilizza per 
tradurre il pacchetto dati nel formato XML appropriato. Si fa questo impostando la 
proprieta TransformationFile o TransformationDocument del componente 
TXMLTransform, proprio come quando si utilizza un componente indipendente 
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TXMLTransform. Se la trasformazione include anche dei nodi definiti dall'utente, e 
necessariio fornire a TransformGetData anche un gestore di evento OnTranslate. 

Non serve specificare il documento di origine di TransformGetData, dato che 
TXMLTransformClient lo preleva dal provider. Tuttavia, se il provider attende dei 
parametri di input, e bene impostarli prima di prelevare i dati. Per fornire questi 
parametri di input prima di prelevare dati dal provider si usa il metodo SetParams. 
SetParams prende due argomenti: una stringa XML da cui estrarre valori del 
parametro e il nome di un file di trasformazione per tradurre il file XML in un 
pacchetto dati. SetParams utilizza il file di trasformazione per convertire la stringa di 
XML in un pacchetto dati, e quindi dal pacchetto dati estrae i valori del parametro. 

Se si desidera specificare in un altro modo il documento di parametro o la 
trasformazione, e possibile ridefinire ambedue gli argomenti. Basta impostare una 
delle proprieta sulla proprieta Transforms etParams per indicare il documento che 
contiene i parametri, o la trasformazione da utilizzare per la conversione, e poi 
quando si chiama SetParams impostare l'argomento che si desidera ridefinire a una 
stringa vuota. Per i dettagli, vedere "Conversione di documenti XML in pacchetti 
dati" a pagina 30-6. 

Una volta configurato TransformGetData e forniti gli eventuali parametri di input, e 
possibile chiamare il metodo GetDataAsXml per prelevare lo XML. GetDataAsXml 
invia i valori dei parametri correnti al provider, preleva un pacchetto dati, lo 
converte in un documento XML e restituisce il documento come stringa. Si puo 
salvare questa stringa in un file: 

XMLTransformClientl->ProviderName = "Provider!."; 

XMLTransformClientl->TransformGetData->TransformationFile = "CustTableToCustXML.xtr" ; 
XMLTransformClientl->TransFormSetParams->SourceXmlFile = " Input Params .xml" ; 
XMLTransformClientl->SetParams ( " 11 , "InputParamsToDP.xtr" ) ; 
AnsiString XML = XMLTransformClientl->GetDataAsXml ( ) ; 

TFileStream pXMLDoc = new TFileStream( "Customers .xml" , fmCreate II fmOpenWrite) ; 
__try 

{ 

pXMLDoc->Write(XML.c_str() , XML . Length ( ) ) ; 

} 

finally 

{ 

delete pXMLDoc; 

} 

Applicazione degli aggiornamenti da un documento XML a un 
provider 



TXMLTransformClient permette anche di inserire tutti i dati tratti da un documento 
XML nel dataset del provider o di cancellare tutti i record di un documento XML dal 
dataset del provider. Per eseguire questi aggiornamenti, si chiama il metodo 
Applyilpdates, passando 

• Una stringa il cui valore e il contenuto del documento XML con i dati da inserire o 
da cancellare. 
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• II nome di un file di trasformazione che puo convertire i dati XML in un pacchetto 
delta di inserimento o di cancellazione. (Quando si definisce il file di 
trasformazione utilizzando XML mapper, si specifica se la trasformazione e per 
inserimento, oppure si cancella pacchetto delta.) 

• II numero di errori di aggiornamento ammessi prima di interrompere l'operazione 
di aggiornamento. Se il numero di record che non e stato possibile inserire o 
cancellare e inferiore al numero specificato, Applyllpdates restituisce il numero di 
errori effettivi. Se il numero di record che non e stato possibile inserire o cancellare 
e superiore al numero specificato, l'operazione viene annullata e nessun 
aggiornamento viene eseguito. 

La seguente chiamata trasforma il documento XML Customers.xml in un pacchetto 
delta e applica tutti gli aggiornamenti indipendentemente dal numero di errori: 

StringListl->LoadFromFile ( "Customers ,xml " ) ; 

nErrors = ApplyUpdates (StringListl->Text, "CustXMLToInsert .xtr" , -1) ; 
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Creazione di applicazioni Internet 

I capitoli inclusi nella sezione "Creazione di applicazioni Internet" presentano i 
concetti fondamentali e le conoscenze necessarie per la creazione di applicazioni da 
distribuire in Internet. 

Non tutti i componenti descritti in questa sezione sono disponibili in tutte le versioni 
di C++Builder. 



Creazione di applicazioni Internet 



Capitolo 




Scrittura di applicazioni CORBA 

CORBA (Common Object Request Broker Architecture) e una specifica adottata da 
OMG (Object Management Group) per affrontare la complessita di sviluppo di 
applicazioni distribuite orientate agli oggetti. 

Come dice il nome, CORBA fornisce un approccio orientato agli oggetti per la 
scrittura di applicazioni distribuite. Questo approccio e l'opposto di quello orientato 
ai messaggi descritto per le applicazioni HTTP nel Capitolo 32, "Creazione di 
applicazioni server per Internet". Sotto Corba, le applicazioni server implementano 
oggetti che possono essere usati da postazione remota dalle applicazioni client, 
tramite interfacce ben definite. 

COM fornisce un altro approccio orientato agli oggetti per le applicazioni distribuite. 
Per maggiori informazioni su COM, vedere il Capitolo 38, "Panoramica sulle 
tecnologie COM". A differenza di COM, pero, CORBA e uno standard che viene 
impiegato in piattaforme diverse da Windows. Questo vuol dire che e possibile 
scrivere client o server CORBA con C++Builder, che sono in grado di comunicare con 
applicazioni abilitate per CORBA in esecuzione su altre piattaforme. 

La specifica CORBA definisce il modo in cui le applicazioni client comunicano con gli 
oggetti che sono implementati su un server. Questa comunicazione e gestita da un 
Object Request Broker (ORB). C++Builder e fortemente integrato con VisiBroker ORB 
di Borland (versione 4.5) in modo da semplificare lo sviluppo in CORBA. 

Oltre alia tecnologia base ORB, che abilita i client a comunicare con gli oggetti su 
macchine server, lo standard CORBA definisce un certo numero di servizi standard. 
Poiche questi servizi usano interfacce ben definite, gli sviluppatori possono scrivere 
client che li usano anche se i server sono scritti da altri produttori. 

Panoramica di un'applicazione CORBA 



Se si sta gia programmando in modo orientato agli oggetti, si potra notare che 
CORBA semplifica notevolmente la scrittura di applicazioni distribuite, in quanto 
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consente di usare oggetti remoti come se fossero locali. Cio e dovuto al fatto che la 
progettazione di un'applicazione CORBA e molto simile a quella di una qualsiasi 
altra applicazione orientata agli oggetti, tranne per il fatto che include un layer 
aggiuntivo per la gestione della comunicazione in rete quando un oggetto risiede su 
un' altra macchina. Questo layer viene gestito da speciali oggetti chiamati stub e 
skeleton. 

Figura 31.1 Struttura di un'applicazione CORBA 




Sui client CORBA, lo stub agisce come un proxy per un oggetto che potrebbe essere 
implementato dallo stesso processo, da un altro processo o su un'altra macchina 
(server). II client interagisce secondo le stesse modalita adottate con un qualunque 
altro oggetto. 

Tuttavia, a differenza della maggior parte di oggetti, lo stub gestisce le chiamate 
d'interfaccia chiamando il software VisiBroker ORB installato sulla macchina client. 
Questo software usa uno Smart Agent (osagent) che viene eseguito in un punto della 
rete locale. Questo agent e un servizio dinamico di directory distribuite che individua 
un server disponibile che fornisce l'implementazione vera e propria dell'oggetto. 

Sul server CORBA il software ORB passa le chiamate d'interfaccia a un skeleton 
generato automaticamente. Questo comunica con il software ORB tramite il Basic 
Object Adaptor (BOA). Usando il BOA, lo skeleton registra l'oggetto con lo Smart 
Agent, ne indica il campo d'azione (specifica se puo essere usato su macchine 
remote) e segnala quando gli oggetti sono istanziati e pronti per rispondere ai client. 



Gli stub e gli skeleton 



La base di un oggetto distribuito sotto CORBA e 1' interfaccia. L'interfaccia e molto 
simile a una definizione di classe, tranne per il fatto che non include informazioni 
sull'implementazione. Le interfacce vengono definite utilizzando il linguaggio di 
definizione delle interfacce di CORBA (IDL). La definizione dell'interfaccia puo 
quindi essere aggiunta al progetto sotto forma di file IDL. Per maggiori informazioni 
sui file IDL, stub e skeleton consultare il manuale di VisiBroker Programmer. Per 



31-2 Guida alia programmazione 



Panoramica di u n ' a pp I i caz i o n e CORBA 

maggiori informazioni sulle operazioni coi file IDL in C++Builder, consultare il 
paragrafo "Definizione delle interfacce dell'oggetto" a pagina 31-5. 

Quando si compila il file IDL, C++Builder genera automaticamente due file .cpp. II 
primo, il file client, contiene l'implementazione della classe stub. L'altro, il file server, 
contiene rimplementazione della classe skeleton. Stub e skeleton forniscono il 
meccanismo che consente alle applicazioni CORBA di coordinare le chiamate di 
interfaccia. II meccanismo di marshaling 

• Prende un'istanza di oggetto nel processo del server e lo rende disponibile al 
codice nel processo del client. 

• Trasferisce gli argomenti di una chiamata d'interfaccia passati dal client e li colloca 
nello spazio di processo dell'oggetto remoto. 

Quando l'applicazione client chiama il metodo di un oggetto CORBA, spinge gli 
argomenti nello stack e chiama oggetto stub. Lo stub scrive gli argomento in un 
buffer di smistamento e trasmette la chiamata in una struttura dell'oggetto remoto. Lo 
skeleton del server apre questa struttura, spinge gli argomenti sullo stack e chiama 
l'implementazione dell'oggetto. In sostanza, lo skeleton ricrea la chiamata del client 
nel proprio spazio d'indirizzo. 

Utilizzo di Smart Agent 



Lo Smart Agent (osagent) e un servizio dinamico distribuito di directory che 
individua un server disponibile che implementa un oggetto. Se si pud scegliere tra 
piu server, lo Smart Agent fornisce il bilanciamento del carico. Questo servizio 
protegge anche dai guasti del server tentando di riavviarlo quando una connessione 
non riesce, oppure, se necessario, individuando un server su un altro host. 

Uno Smart Agent deve essere awiato su almeno un host della rete locale, nel punto 
in cui la rete fa riferimento ad un'altra rete all'interno della quale pud essere inviato 
un messaggio di trasmissione. II software ORB individua uno Smart Agent 
utilizzando un messaggio di trasmissione. Se il la rete include piu Smart Agent, la 
tecnologia ORB usa quello che risponde per primo. Una volta individuato lo Smart 
Agent, il software ORB usa un protocollo UDP punto a punto per comunicare con lo 
Smart Agent. Questo protocollo consuma meno risorse di rete di una connessione 
TCP. 

Quando una rete include piu Smart Agent, ciascuno di essi riconosce un sottogruppo 
di oggetti disponibili, e comunica con gli altri Smart Agent per individuare gli oggetti 
che non e in grado di riconoscere direttamente. Se uno Smart Agent termina 
inaspettatamente, gli oggetti dei quali tiene la traccia vengono registrati 
automaticamente di nuovo con un altro Smart Agent disponibile. 

Per informazioni sulla configurazione e sull'uso degli Smart Agent sulle reti locali, 
consultare il manuale VisiBroker Installation and Administration Guide. 
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Attivazione delle applicazioni server 



Quando l'applicazione server viene avviata, essa informa 1' ORB (tramite il Basic 
Object Adaptor) degli oggetti che possono accettare le chiamate del client. Questo 
codice per inizializzare l'ORB e per informarlo del fatto che il server e attivo e pronto, 
viene aggiunto automaticamente all'applicazione dal wizard usato per avviare 
l'applicazione server CORBA. 

Normalmente, le applicazioni server CORBA vengono awiate manualmente. Pero, e 
possibile usare l'Object Activation Daemon (OAD) per avviare i server o istanziare i 
loro oggetti solo quando i client hanno bisogno di usarli. 

Per usare l'OAD, occorre registrarvi i propri oggetti. La registrazione di oggetti con 
l'OAD memorizza le associazioni tra gli oggetti stessi e l'applicazione server che li 
implementa in un database chiamato Implementation Repository. 

Una volta che nell'Implementation Repository c'e una voce per l'oggetto, l'OAD 
Simula l'applicazione per l'ORB. Quando un client richiede l'oggetto, l'ORB contatta 
l'OAD come se fosse l'applicazione server. L'OAD quindi evade la richiesta del client 
per il server vero e proprio, lanciando se necessario l'applicazione. 

Per informazioni dettagliate sulla registrazione degli oggetti con l'OAD, consultare il 

VisiBroker Programmer's Guide. 

Binding dinamico delle chiamate alle interfacce 



Normalmente, i client CORBA usano un binding statico per chiamare le interfacce 
degli oggetti sul server. Questo approccio ha molti vantaggi, che comprendono 
prestazioni piu rapide e il controllo del tipo in fase di compilazione.Tuttavia, ci sono 
casi in cui si puo conoscere solo in fase di esecuzione quale interfaccia si intende 
usare. A volte, tuttavia, puo succedere che non si sappia quale oggetto o interfaccia 
utilizzare fino al momento dell'esecuzione. In questi casi, C++Builder permette di 
eseguire il bind delle interfacce dinamicamente in fase di esecuzione. 

Se si usa un binding dinamico, esso risulta d'aiuto nel registrare le interfacce con 
l'lnterface Repository. 

Per maggiori informazioni su come utilizzare il binding dinamico nelle applicazioni 
client CORBA, consultare la sezione "Dynamic Invocation Interface (DII)" nel 
manuale VisiBroker Programmer's Guide. 

Scrittura di server CORBA 



C++Builder include diversi wizard per semplificare il processo di sviluppo di server 
CORBA. I passi seguenti descrivono come creare un server CORBA utilizzando 
C++Builder: 

1 Definire le interfacce dell'oggetto. Queste interfacce definiscono il modo in cui le 
applicazioni client interagiscono col server. Inoltre, esse rappresentano la base da 
cui C++Builder crea le implementazioni di stub e skeleton. 
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2 Utilizzare il wizard CORBA server per creare una nuova applicazione server 
CORBA che includa il codice per inizializzare all'avvio BOA e ORB di CORBA. 

3 Compilare i file IDL che contengono le definizioni dell'interfaccia in classi skeleton 
(e classi stub). 

4 Utilizzare il wizard CORBA object per definire (e istanziare) le classi 
dell'implementazione. 

5 Implementare gli oggetti CORBA completando le classi create nel passo 5. 

6 Se necessario, modificare le interfacce CORBA e includere tali modifiche nelle 
classi deH'implementazione. 

Oltre ai passi elencati in precedenza, si puo scegliere di registrare i file IDL con 
l'lnterface Repository e Object Activation Daemon. 

Definizione delle interfacce dell'oggetto 



Le interfacce degli oggetti CORBA vengono definite utilizzando il linguaggio di 
definizione delle interfacce di CORBA (IDL). IDL ha una sintassi simile a quella del 
C++, tanto che un file IDL e molto simile a un file header di C++. II file IDL si 
comporta anche in odo molto simile ad un file header, dichiarando le interfacce che 
possono essere condivise, proprio come un file header dichiara le classi che possono 
essere condivise. In CORBA, comunque, le interfacce (le classi) vengono condivise 
con le altre applicazioni piuttosto che con (oppure in aggiunta ad) altri moduli nella 
stessa applicazione. 

II termine IDL e utilizzato in contesti differenti per fare riferimento a linguaggi di 
definizione di interfacce simile ma non identici. Esiste un IDL CORBA (definito da 
OMG), un IDL Microsoft (utilizzato per COM) e un IDL DCE. Per maggiori 
informazioni sull'IDL CORBA, consultare la Guida in linea. 

Per definire un nuovo file IDL dall'interno di C++Builder, scegliere File I New I Other 
e selezionare dalla pagina Multitier della finestra di dialogo New Items l'opzione 
CORBA IDL File. Verra aperto l'editor del codice con un file IDL vuoto e il file IDL 
verra aggiunto al progetto corrente. 

Se esiste gia un file IDL che definisce gli oggetti, e possibile semplicemente 
aggiungere questo file al progetto scegliendo Project I Add to Project, selezionando 
IDL files come tipo di file e selezionando quindi il file IDL esistente. 

Utilizzo del CORBA Server Wizard 



Per cominciare un nuovo progetto CORBA Server, scegliere l'opzione File I New I 
Other e, dalla pagina di Multitier della finestra di dialogo di New Items, scegliere 
l'icona identificata come CORBA Server. II wizard CORBA Server permette di 
indicare se si desidera creare un' applicazione per console oppure un'applicazione 
per Windows. 



Scrittura di applicazioni CORBA 31-5 



Scrittura di server CORBA 

Se si sta creando un'applicazione per console, e possibile specificare se il server 
utilizzera le classi della VCL. Se non si seleziona la casella di controllo VCL, tutto il 
codice generato puo essere portato su altre piattaforme. 

Oltre a scegliere il tipo di applicazione, e possibile includere nel progetto qualsiasi 
file IDL esistente, oppure e possibile specificare che si desidera includere un nuovo 
file IDL vuoto. II progetto del server eventualmente deve includere uno o piu file IDL 
che definiscono le interfacce utilizzate dai client per comunicare col server. 

ISe non si aggiungono i file IDL all'inizio di un progetto per server CORBA, e sempre 
possibile aggiungerli in seguito scegliendo l'opzione Project I Add to Project (per i file 
IDL e esistenti) oppure scegliendo dalla pagina Multitier della finestra di dialogo 
New Items l'opzione CORBA IDL file (per definire un nuovo file IDL). 

Una volta indicato il tipo di server desiderato e aver fatto clic su OK, il wizard 
CORBA Server creera un nuovo progetto server del tipo specificato, aggiungendo al 
file di progetto le librerie CORBA e il codice di avvio per inizializzare ORB (Object 
Request Broker) e il BOA (Basic Object Adaptor). 

II codice generato in automatico dichiara due variabili, orb e boa che e possibile 
utilizzare per comunicare con ORB e BOA: 

CORBA: :0RB_var orb = CORBA: :0RB_init (argc, argv) ; 
CORBA: :B0A_var boa = orb->BOA_init (argc, argv); 

Se e stata specificata un'applicazione per console, si vedra anche la linea seguente: 

boa->impl_is_ready ( ) ; 

Questa chiamata consente all'applicazione di ricevere messaggi dal BOA, in modo 
molto simile a come un loop di messaggi di Windows consente a un'applicazione 
Windows di ricevere i messaggi da Windows. (Le applicazioni Windows utilizzano il 
loop di messaggi di Windows anche per i messaggi CORBA). 

Per maggiori informazioni su ORB e BOA, consultate la documentazione di 
VisiBroker. 

Generazione di stub e skeleton da un file IDL 



Dopo aver aggiunto a un progetto CORBA il file IDL che descrive le interfacce 
CORBA, e possibile generare le classi stub e skeleton che gestiscono la 
comunicazione tra il server e le sue applicazioni client. 

Per generare le classi stub e skeleton, e sufficiente compilare il file IDL. E possibile 
compilare questo file scegliendo l'opzione Project I Compile Unit quando il file IDL e 
visualizzato nell'editor di codice, oppure fare clic destro sul file IDL nel project 
manager e scegliere Compile. II compilatore IDL genera due nuovi file che appaiono 
nell'editor di codice e nel project manager. Questi sono 

• II file del server (xxx s.cpp). Questo file contiene l'implementazione delle classi 
skeleton. 

• II file client (xxx c.cpp). Questo file contiene l'implementazione delle classi stub. 
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La pagina CORBA della finestra di dialogo Project Options consente di influenzare il 
modo in cui vengono generate a partire dal file IDL le classi stub e skeleton. Ad 
esempio, e possibile specificare che si desidera includere nel progetto solo la unit 
generata per il server, oppure specificare che si vogliono includere le classi Tie solo se 
il server utilizza il modello della delega (descritto nella sezione "Uso del modello di 
delega" a pagina 31-8). Queste opzioni influenzano la compilazione di tutti i file IDL 
inclusi nel progetto corrente. 

Uso del Wizard CORBA Object Implementation 



Per implementare gli oggetti CORBA definiti nel file IDL, si devono creare classi di 
implementazione che corrispondano a ogni classe skeleton. Per fare questo, scegliere 
l'opzione File I New I Other, e dalla pagina Multitier della finestra di dialogo New 
Items, scegliete l'opzione CORBA Object Implementation. In tal modo verra attivato 
il wizard CORBA Object Implementation. 

II wizard CORBA Object Implementation elenca tutte le interfacce definite nei file 
IDL inclusi nel progetto. Scegliere un file IDL e, a partire da quel file IDL, selezionare 
l'interfaccia che si desidera implementare. Assegnare un nome alia classe di 
implementazione e specificare il nome della unit dei file .h e .cpp che conterranno la 
definizione e l'implementazione dell'oggetto. 

Nel Wizard, indicare se le classi di implementazione dovrebbero essere discendenti 
delle classi skeleton generate in automatico, o se si sta utilizzando un modello di 
delega (classi tie). Se si sta utilizzando il modello di delega (e l'applicazione server 
utilizza la VCL), e anche possibile chiedere al wizard di creare un modulo dati per le 
classi dell'implementazione. Cio consente di aggiungere i componenti, che si 
potrebbero voler utilizzare durante la scrittura dell'implementazione, al modulo dati 
della stessa. 

E possibile richiedere al wizard di aggiungere del codice per istanziare gli oggetti 
CORBA all'awio dell'applicazione, cosi da renderli disponibili a ricevere le richieste 
dei client. Se si istanziano gli oggetti in fase di avvio, e necessario assegnar loro un 
nome in modo che i possano essere localizzati dai client. Questo nome viene passato 
al costruttore come parametro, e non e il nome della variabile che referenzia l'istanza. 
Quando le applicazioni client eseguono il bind all'oggetto CORBA, utilizzano questo 
nome per indicare l'oggetto desiderato. 

Facendo clic su OK, il wizard CORBA Object Implementation genera la definizione 
per la classe dell'implementazione e genera un'implementazione in cui ogni metodo 
ha un corpo vuoto. Inoltre, pud aggiungere anche del codice per istanziare gli 
oggetti, nel caso questa possibility sia stata indicata. 

Prima che queste variazione vengano aggiunte al progetto, e possibile rivederle e 
modificarle. Per fare cio, prima di fare clic su OK, selezionare la casella Show 
Updates. Dopo avere rivisto le variazioni e averle eventualmente modificate, esse 
vengono aggiunte al progetto. Se non si sceglie di rivedere e modificare le variazioni 
all'uscita dal wizard, sara possibile modificarle in seguito nell'editor del codice. 

Per implementare piu interfacce, e necessario eseguire varie volte il wizard CORBA 
Object Implementation, una volta per ciascuna interfaccia. Tuttavia, e possibile 
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richiedere al wizard di generare piu istanze di una singola classe di implementazione 
fornendo piu nomi. 

Istanze di oggetti CORBA 

Per ogni oggetto CORBA, e necessario decidere come dovra essere istanziato. 
Esistono due possibilita: 

• L'oggetto viene istanziato all'avvio dell'applicazione server. In questo caso, 
l'oggetto e disponibile alle applicazioni client ad ogni richiesta fatta al server. 

• L'oggetto viene istanziato in risposta a una richiesta del client (una chiamata a un 
metodo di un oggetto esistente). In questo caso, l'applicazione server istanzia 
l'oggetto all'interno dell'implementazione di un metodo di interfaccia, e 
restituisce un riferimento all'oggetto da quel metodo. 

Se l'oggetto viene istanziato all'avvio dell'applicazione, selezionare la casella 
Istantiate in main nel wizard CORBA Object. II wizard aggiunge al file della sorgente 
del progetto il codice necessario per istanziare direttamente la classe 
dell'implementazione. E possibile esaminare questo codice scegliendo 
1'opzioneProject I View Source. Dopo le linee inserite dal Wizard CORBA Server per 
chiamare ORB_init e BOA_init e prima della chiamata impl_is_ready(), e possibile 
trovare il codice che istanzia la classe di implementazione e informa il boa che 
l'oggetto puo accettare le richieste: 

MyObjlmpl MyObject_TheObject ( "TheObject " ) ; // create the object instance 
boa->obj_is_ready (&MyObject_TheObject) ; // inform the boa it can take requests 

E possibile aggiungere codice di inizializzazione tra il costruttore e la chiamata a 
obj_is_ready: 

MyObjlmpl MyObject_TheObject ("TheObject") ; // create the object instance 
MyObject_TheObject. Initialize (50000) ; 

boa->obj_is_ready (&MyObject_TheObject) ; // inform the boa it can take requests 

Se si utilizzano le classi tie (vedere di seguito), sara presente anche una chiamata per 
istanziare la classe tie. 

Se gli oggetti non vengono istanziati all'avvio, si puo chiamare il costruttore (e, se 
necessario, il costruttore della classe tie) da un metodo e ottenere un riferimento 
all'istanza dell'oggetto. E buona norma aggiungere anche una chiamata al metodo 
obj_is_ready del BOA's. 

Agli oggetti che accettano chiamate da client CORBA occorre assegnare un nome, 
altrimenti i client non saranno in grado di trovarli. Agli oggetti transitori (oggetti 
creati in risposta a chiamate del client e restituiti come riferimenti) non e necessario 
assegnare un nome. 

Uso del modello di delega 

Per impostazione predefinita, gli oggetti CORBA sono discendenti di classi skeleton 
create al momento della compilazione di un file IDL. Cio significa che le classi 
dell'oggetto ereditano tutto il codice che coordina le chiamate all'interfaccia e 
interagisce col BOA. Tuttavia, se si desidera esporre oggetti nel server CORBA gia 
scritti in precedenza, oppure derivati da classi della VCL (che non consente l'eredita 
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multipla), o che si vogliono condividere con altre applicazioni non-CORBA, e 
possibile utilizzare classi server che non dipendono da CORBA oppure i file server 
generati. 

L'applicazione deve utilizzare un modello di delega per esporre gli oggetti che non 
discendono da una classe skeleton. Un modello della delega e un modello in cui le 
istanze delle classi skeleton non implementano direttamente gli oggetti CORBA, ma 
piuttosto passano una classe di interfaccia a una classe di implementazione 
completamente separata. Cio significa che la classe di implementazione non e un 
discendente di skeleton, ma piuttosto che viene chiamato dallo skeleton. 

Per utilizzare il modello di delega, si devono generare le classi tie al momento della 
compilazione dei file IDL. Prima di compilare i file IDL, scegliere l'opzione Project I 
Options, e sulla pagina IDL della finestra di dialogo di Project Options, selezionare la 
casella per generare le classi tie. 

Una volta compilato il file IDL, oltre alia classe skeleton, il file del server contiene una 
classe tie speciale. Questa classe tie agisce come un proxy per la classe 
dell'implementazione, e, relativamente alle implementazioni di metodi, essa delega 
la (passa la chiamata alia) classe dell'implementazione. 

Quando si utilizza il wizard CORBA Object per definire la classe 
dell'implementazione, scegliere il pulsante di opzione Delegation (Tie), in modo tale 
che la classe dell'implementazione non venga creata come un discendente della 
classe skeleton. II wizard CORBA Object aggiunge un commento accanto alia 
dichiarazione della classe. Non rimuovere questo commento: e utilizzato da 
C++Builder per identificare la classe come una classe di implementazione di CORBA. 

Oltre a cambiare il modo in cui il wizard CORBA Object genera la classe 
dell'implementazione, la scelta del pulsante Tie influenza anche tutto il codice 
generato in automatico che istanzia l'oggetto. 

Quando l'applicazione server istanzia la classe dell'implementazione, deve istanziare 
immediatamente dopo la classe tie associata, passando al costruttore l'istanza della 
classe di implementazione sotto forma di argomento. Se la classe 
dell'implementazione viene istanziata all'awio, il codice necessario viene generato 
automaticamente dal wizard CORBA Object. Tuttavia, se si sta istanziando 
dinamicamente l'oggetto CORBA in fase di esecuzione, si deve aggiungere questo 
codice manualmente. Per esempio: 

MyObjlmpl myobjO; // instantiate implementation object 
_tieJ4y0b]<My0b]Impl> tieobj (myobj , "InstanceName" ) ; 

Visualizzazione e modifica dei cambiamenti 

Prima di aggiungere qualsiasi modifica al progetto, e buona norma esaminare ed 
eventualmente variare tali modifiche. Questa operazione ha due scopi: 

• Prendere atto di tutte le modifiche apportate al progetto.Non verra aggiunto alcun 
codice creato in automatico che potrebbe generare un comportamento di cui non si 
e a conoscenza. 



Scrittura di applicazioni CORBA 31-9 



Scrittura di server CORBA 

• E possibile personalizzare le modifiche senza doverle andare a cercare in tutti i file 
dell'implementazione. Cio risulta particolarmente utile se si stanno aggiungendo 
delle modifiche a un file che contiene gia molto codice. 

Per esaminare il codice e apportare eventuali modifiche, utilizzare la finestra di 
dialogo Project Updates. Questa finestra di dialogo viene visualizzata quando si 
seleziona l'opzione Show Updates in un qualsiasi wizard CORBA oppure quando si 
sceglie il comando Edit I CORBA Refresh. 

La finestra di dialogo Project Updates elenca le modifiche in un pannello sulla 
sinistra. E possibile rifiutare tutte le modifiche deselezionando la casella che appare 
alia sua sinistra. Se si rifiuta una modifica, questa non viene inserita nel progetto, e 
sara necessario scrivere manualmente il codice corrispondente. 

Le modifiche sono elencate nell'ordine in cui sono state fatte. Eliminando una 
modifica si potrebbero rimuovere altre modifiche che dipendono da essa. Per 
esempio, deselezionando la creazione di un nuovo file, verranno deselezionate le 
modifiche che rappresentano il codice aggiunto a quel file. 

Man mano che si scorre l'elenco di modifiche, si vedra il codice aggiunto nel pannello 
del codice. II file che e stato modificato per contenere quel codice viene elencato nella 
parte inferiore del pannello del codice. 

Se si desidera personalizzare una modifica e possibile modificare il pannello del 
codice. Per esempio, si potrebbe voler aggiungere una ulteriore classe antenato alia 
classe dell'implementazione, in modo che erediti il comportamento di una delle 
classi esistenti.Si potrebbe anche aggiungere del codice per implementare i metodi, 
compilando i corpi dei metodi vuoti generati in automatico. 

Terminata la revisione e l'eventuale modifica dei cambiamenti generati in 
automatico, fare clic su OK per aggiungerli al progetto e includere anche le modifiche 
apportate. Se non desidera accettare alcuna modifica, annullare la finestra di dialogo. 

Implementazione degli oggetti CORBA 



Se non si sta utilizzando un modello di delega, la classe dell'implementazione e un 
discendente della classe skeleton generata all'atto della compilazione del file IDL. In 
caso contrario, non esistono antenati espliciti alle classi dell'implementazione. E 
possibile modificare questa definizione della classe in modo che erediti da un'altra 
classe nell'applicazione server, ma non si devono rimuove eventuali eredita esistenti 
da una classe skeleton. 

Si esamini la seguente dichiarazione estratta da un file IDL, account. idl: 

interface Account { 
float balanced ; 

}; 

Quando si compila il file IDL (senza le classi tie), l'header del server generato 
(account_s.hh) include la dichiarazione di una classe skeleton con metodi virtuali 
puri per ogni metodo dell'interfaccia. 
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II wizard CORBA Object crea una unit dell'implementazione che deriva una classe di 
implementazione dalla classe skeleton (_sk_Account). II file header assomiglia al 
seguente: 

#ifndef interfacelServerH 
♦define InterfacelServerH 
♦include "account_s.hh" 

// 

class Accountlmpl: public _sk_ Account 
{ 

protected : 
public : 

Accountlmpl (const char *object_name=NULL) ; 
CORBA: : float balanced ; 

}; 

#endif 

Si potrebbero aggiungere a questa definizione di classe altri membri dati o metodi 
potrebbero occorre per l'implementazione. Per esempio: 

#ifndef InterfacelServerH 
♦define InterfacelServerH 
♦include "account_s.hh" 

// 

class Accountlmpl: public _sk_ Account 
{ 

protected : 

CORBA: : float _bal; 
public : 

void InitializefCORBA: :float startbal); // not available to clients 
Accountlmpl (const char *object_name=NULL) ; 
CORBA: : float balanced ; 

}; 

#endif 

Questi metodi e proprieta aggiuntivi sono rese disponibili dall'applicazione server 
ma non accessibili dai client. 

Completare nel file .cpp generato il corpo principale della classe 
dell'implementazione, in modo da ottenere un oggetto CORBA funzionante: 

Accountlmpl: :AccountImpl (const char *object_name) : 
_sk_Account (object_name) 

{ 
} 

CORBA: :float Accountlmpl: :balance() 

{ 

return _bal; 

}; 

void InitializefCORBA: : float startbal) // not available to clients 

{ 

_bal = startbal; 
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} 

A partire dal server CORBA, e possibile scrivere del codice in grado di interagire col 
BOA. Per esempio, utilizzando il BOA, e possibile nascondere temporaneamente, o 
disattivare, gli oggetti server e successivamente riattivarli. Per maggiori informazioni 
su come scrivere del codice in grado di interagire col BOA, consultare il manuale 

VisiBroker Programmer's Guide. 

Protezione da conflitti di thread 

Per impostazione predefinita, le applicazioni CORBA sono multi-thread. Cio 
significa che quando si implementano gli oggetti CORBA e necessario cautelarsi da 
eventuali conflitti di thread. 

A meno che si specifichi altrimenti, il BOA unisce i thread client, il che significa che 
tali richieste dei client possono utilizzare qualsiasi thread disponibile. E possibile, 
tuttavia, fare in modo che ciascun client utilizzi sempre lo stesso thread avviando il 
BOA imponendo un certo numero di thread per sessione. Se ciascun client utilizza 
sempre lo stesso thread, e possibile memorizzare le informazioni persistenti del client 
in variabili di thread. Per informazioni su come impostare la politica di threading 
quando si avvia BOA, consultare il manuale VisiBroker Programmer's Guide. 

La libreria VisiBroker include delle classi che possono essere d'aiuto nel proteggere il 
codice da eventuali conflitti di thread. Queste vengono definite nel file header 
vthread.h, installato nella directory dei file include di VisiBroker. Le classi di 
supporto per il thread di VisiBroker includono un mutex (VisMutex), una variabile di 
condizione (VISCondition) e unblocco in lettura/ scrittura che funziona, piu o meno, 
come il sincronizzatore multi-read /exclusive- write della VCL (VISRWLock). Uno dei 
benefici derivanti dall'utilizzo di queste classi e che sono portabili su tutte le 
piattaforme supportate da VisiBroker. 

Per esempio, e possibile proteggere dati di istanza aggiungendo un campo VisMutex 
alia classe dell'implementazione: 

class A { 

VISMutex _mtx; 

} 

In seguito, quando sara necessario sincronizzare l'accesso a dati di istanza, sara 
possibile bloccare il mutex dall'interno di un qualsiasi metodo che accede i dati di 
istanza: 

void A: : AccessSharedMemory ( . . . ) 

{ 

VlSMutex_var lock(_mtx); // acquires a lock that is released on exit 
// add code here to access the instance data 

} 

Occorre notare che il mutex viene rilasciato al termine dell'esecuzione di 
AccessSharedMemory, anche se viene sollevata un'eccezione dall'interno del corpo 
del metodo. 

Se si sta utilizzando la VCL nell'applicazione server, e bene ricordare che C++Builder 
include varie classi che possono essere d'aiuto nella protezione contro eventuali 
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conflitti di thread. Per maggiori informazioni, consultare il Capitolo 11, "Scrittura di 
applicazioni multi-thread". 

Modifica delle interfacce CORBA 



Se si apportano delle modifiche alle interfacce nei file IDL dopo aver generato le 
classi dell'implementazione utilizzando il wizard CORBA Object, C++Builder 
consente di aggiornare automaticamente il progetto del server in modo da 
rispecchiare tali modifiche, senza perdere il lavoro gia fatto scrivendo le classi 
dell'implementazione. 

Dopo aver modificato i file IDL, scegliere il comando Edit I CORBA Refresh. Questo 
comando ricompila i file IDL cosi che il file del client e del server generati in 
automatico rispecchino le nuove definizioni dell'interfaccia e opzioni correnti del 
compilatore. Se i file IDL vengono compilati con successo, e possibile esaminare e 
modificare i cambiamenti apportati da C++Builder utilizzando la finestra di dialogo 
Project Updates. 

Se C++Builder non trova l'interfaccia che corrisponde a una delle classi 
dell'implementazione esistenti, chiede se e stato cambiato nome all'interfaccia. Se si 
risponde di si, verra chiesto di indicare in che modo sono state rinominate le 
interfacce, in modo che le classi di implementazione possano essere fatte 
corrispondere correttamente alle interfacce. 

Se si usa il comando Refresh di CORBA, alle classi di implementazione vengono 
aggiunti dei nuovi metodi e le dichiarazioni vengono aggiornate in modo da 
riflettere le modifiche apportate ai metodi e agli attributi esistenti. Tuttavia, alcune 
modifiche non provocano alcun aggiornamento. In particolare, se si cancella un 
metodo o un attributo, il relativo codice non viene cancellato. Invece, i metodi 
cancellati continuano a far parte della classe, ma non sono piu disponibili ai client 
CORBA. Analogamente, se si cambia il nome a un metodo o a un attributo, questa 
modifica viene trattata come una cancellazione e un'aggiunta: il vecchio metodo o 
attributo viene conservato e viene generato del codice per un nuovo metodo o 
attributo. 

Registrazione delle interfacce del server 



Benche non sia necessario registrare le interfacce del server se si sta utilizzando il 
bindind statico delle chiamate dei client agli oggetti del server, la registrazione delle 
interfacce e un'operazione consigliata.Esistono due programmi di utilita che 
consentono di registrare le interfacce: 

• L'Interface Repository. Se si registrano le interfacce con Interface Repository, i 
client possono ottenere da programma le informazioni sulle interfacce, se 
utilizzano l'interfaccia di chiamata dinamica (DII). Per maggiori informazioni 
sull'utilizzo della DII, consultare la sezione "Utilizzo dell'interfaccia di chiamata 
dinamica" a pagina 31-16. La registrazione mediante l'Interface Repository risulta 
anche essere un modo conveniente per consentire ad altri sviluppatori di vedere le 
interfacce durante la scrittura delle applicazioni client. 
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E possibile registrare le interfacce con l'lnterface Repository scegliendo il comando 
Tools I IDL Repository. 

• L'Object Activation Daemon. Effettuando la registrazione con Y Object Activation 
Daemon (OAD), non e necessario lanciare il server o istanziare gli oggetti finche 
non sono necessari ai client. In questo modo e possibile risparmiare risorse sul 
sistema server. 

Scrittura di client CORBA 



Quando si scrivete un client CORBA, il primo passo e quello di garantire che 
l'applicazione client possa parlare col software ORB sulla macchina client. Per fare 
cio, utilizzare il wizard CORBA Client. Scegliere il comando File I New I Other e, dalla 
pagina Multitier della finestra di dialogo New Items, scegliete quindi l'icona 
identificata come CORBA Client. II wizard CORBA Client consente di indicare se si 
vuole creare un'applicazione per console oppure un'applicazione per Windows. 

In modo analogo a un'applicazione server CORBA, e possibile specificare se 
l'applicazione client CORBA utilizzera le classi VCL. Se non si seleziona la casella di 
controllo VCL, tutto il codice generato puo essere portato su altre piattaforme. 

Nel wizard CORBA Client, includere tutti i file IDL che definiscono le interfacce degli 
oggetti del server che si vogliono utilizzare. Benche sia possibile creare 
un'applicazione client CORBA senza includere alcun file IDL (aggiungendo 
esplicitamente al progetto una unit client generata), questa non e la modalita 
preferita. Una volta che il progetto include i file IDL per le interfacce del server, e 
possibile utilizzare il wizard Use CORBA Object per eseguire il bind agli oggetti sul 
serverNote 

Se i file IDL non vengono aggiunti quando si inizia un progetto di un client CORBA, 
e sempre possibile aggiungerli in seguito mediante il comando Project I Add to 
Project. 

II wizard CORBA Client crea sempre un nuovo progetto client del tipo specificato, 
aggiungendo le librerie CORBA al file di progetto e il seguente codice di awio per 
inizializzare l'ORB (Object Request Broker). 

CORBA: :0RB_var orb = CORBA: :0RB_init (argc, argv) ; 

Se si ha intenzione di passare interfacce callback al server CORBA, sara necessario 
inizializzare il BOA (Basic Object Adaptor) anche nell'applicazione client. Per fare 
cio, e sufficiente selezionare nel wizard la casella di controllo opportuna. 

Quindi, procedere con la scrittura dell'applicazione nello stesso modo in cui si scrive 
qualsiasi altra applicazione C++Builder. Comunque, quando si vorranno utilizzare 
oggetti che sono definiti nell'applicazione server, non si operera direttamente con 
un'istanza dell'oggetto. Invece, si otterra un riferimento a un oggetto CORBA e si 
lavorera con quello. II riferimento all'oggetto CORBA puo essere ottenuto in due 
modi, a seconda che si desideri utilizzare il binding statico o dinamico. 

Per utilizzare il binding statico, e possibile richiamare il wizard Use CORBA Object 
scegliendo il comando Edit I Use CORBA Object. L'utilizzo del binding statico e piu 



31-14 Guida alia programmazione 



Scrittura di client CORBA 

rapido rispetto all'uso di quello dinamico, oltre a fornire ulteriori vantaggi quali il 
controllo sui tipi in fare di compilazione e il completamento del codice. 

A volte, tuttavia, pud succedere che non si sappia quale oggetto o interfaccia 
utilizzare fino al momenta dell'esecuzione. In questi casi, si puo utilizzare il binding 
dinamico. II binding dinamico utilizza un oggetto CORBA generico che passa le 
richieste al server utilizzando uno tipo di CORBA particolare denominate Any. 

Uso di stub 



Le classi stub vengono generate automaticamente quando si compila il file IDL. Esse 
sono definite nei file client generati, i cui nomi assumono la forma NomeBase_c.cpp e 
NomeBase_c.hh. 

Nella pagina CORBA della finestra di dialogo Project Options e possibile indicare a 
C++Builder di generare solamente i file del client (stub) e non i file del server. 

Quando si scrive un client CORBA, non si modifica il codice nei file client generati. Si 
istanziano, invece, le classi stub nei punto in cui vengono utilizzate. Per fare cio, 
scegliere Edit I Use CORBA Object per attivare il wizard Use CORBA Object. 

Nei wizard Use CORBA Object, specificare il file IDL che contiene l'interfaccia a cui si 
desidera accedere e selezionare l'interfaccia che verra utilizzata. Se si vuole eseguire 
il bind solo a una specifica istanza con un certo nome dell'oggetto CORBA, e 
possibile indicare, se si vuole, un nome per l'Oggetto CORBA. 

II wizard Use CORBA Object consente di scegliere fra vari meccanismi per eseguire il 
bind a un oggetto del server. 

• Se l'applicazione client e un'applicazione Windows che utilizza la VCL, puo creare 
una proprieta sulla scheda dell'applicazione per contenere un'istanza della classe 
stub dell'oggetto CORBA. E possibile utilizzare quindi questa proprieta come 
un'istanza dell'oggetto del server CORBA. 

• Se si sta creando un'applicazione per console, il wizard puo istanziare la classe 
stub come una variabile nella funzione main() dell'applicazione. In modo analogo, 
se si sta creando un'applicazione Windows, puo istanziare la classe stub come una 
variabile nella funzione WinMain(). 

• Sia che si stia creando un'applicazione Windows o un'applicazione per console, il 
wizard puo aggiungere una proprieta a una classe esistente in una qualsiasi unit 
specificata, oppure iniziare una nuova classe che include una proprieta per 
l'istanza dello stub. 

Indipendentemente dal meccanismo scelto, il wizard aggiunge tutti i file header 
necessari e genera il codice che esegue il bind di una variabile stub o di una proprieta 
all'oggetto del server CORBA. Per esempio, il codice seguente istanzia lo stub per 
un'interfaccia del server, di nome MyServerObj nella funzione main() di 
un'applicazione per console: 

♦include <corba.h> 
♦include <condefs.h> 
♦include "MyServerObj _c.hh" 
♦pragma argsused 
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int main(int argc, char* argv[]) 

{ 

try 

{ 

// Initialize the ORB 

CORBA: :ORB_var orb = CORBA: :ORB_init (argc, argv) ; 
MyServerObj_var TheObject = MyServerObj : :_bind( "InstanceName" ) ; 

} 

catch (const CORBA: : Exceptions e) 
{ 

cerr << e << endl; 
return ( 1 ) ; 

} 

return 0; 

} 

Se si copia il codice che esegue il bind a un oggetto del server in un'altra parte 
dell'applicazione, e bene accertarsi che la variabile stub sia una variabile locale 
oppure il membro dati di una classe. Le variabili stub globali sono abbastanza 
delicate in quanto non possono rilasciare il proprio contatore dei riferimenti di 
CORBA prima che venga rilasciata la variabile orb. Se si deve utilizzare 
necessariamente una variabile stub globale, assicurarsi di annullare il bind 
impostando la variabile a NULL prima di rilasciare l'orb. 

Se l'applicazione client include solamente la unit client generata (BaseName_c), non e 
possibile utilizzare il wizard CORBA Object per eseguire il bind a oggetti del server. 
Tale codice dovra essere generato dal programmatore. Si potrebbe anche voler 
scrivere del codice personale per eseguire il bind in modo da sfruttare le opzioni di 
bind di VisiBroker. (Per esempio, si potrebbe voler specificare un determinato server, 
disattivare la funzione che tenta automaticamente di rieseguire il bind a un server nel 
caso vada perda la connessione CORBA, e cosi via). Per maggiori informazioni sulla 
scrittura di codice per eseguire il bind a oggetti del server, consultare la 
documentazione di VisiBroker. 




Utilizzo dell'interfaccia di chiamata dinamica 



L'interfaccia di chiamata dinamica (DII) consente alle applicazioni client di chiamare 
gli oggetti server senza utilizzare una classe stub che coordini in modo esplicito le 
chiamate dell'interfaccia. Poiche DII deve codificare tutte le informazioni di tipo 
prima che il client invii una richiesta e quindi deve decodificare tali informazioni sul 
server, il processo risulta piu lento rispetto all'utilizzo di una classe stub. 

Per utilizzare la DII in un'applicazione client, si deve 

1 Creare un oggetto CORBA generico, che funziona come un oggetto stub, tranne 
per il fatto che la sua implementazione non include il codice per coordinare le 
richieste. Sara necessario fornire 1TD del repository dell'oggetto per indicare quale 
oggetto dovrebbe ricevere le richieste della DII: 

CORBA: : Obj ect_var diiObj; 
try 

{ 

diiObj = orb->bind("IDL:ServerObj:1.0") ; 
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} catch (const CORBA: : Exceptions E) 

{ 

// handle the bind exception. 

} 

2 Quindi, si deve utilizzare l'oggetto CORBA generico per creare un oggetto 
richiesta per un determinate metodo dell'oggetto rappresentato dall'oggetto 
CORBA generico: 

CORBA: :Request_var req = diiObj->_request ( "methodName" ) ; 

3 Quindi, si devono aggiungere tutti gli argomenti accettati dal metodo. Gli 
argomenti vengono aggiunti a un elenco di richieste di tipo CORBA::NVList_ptr. 
Ciascuno argomento e di tipo CORBA::Any, che e simile a un Variant. E necessario 
usare il tipo CORBA: Any poiche un elenco di valori con nome (ORBA::NVList) 
deve gestire qualsiasi lista di argomenti, che a sua volta pud includere valori di 
qualsiasi tipo. 

CORBA: :Any arg; 

arg «= (const char *) "argvalue" ; 

CORBA: :NVList_ptr arguments = req->arguments ( ) ; 

arguments->add_value( "argl" , arg, CORBA: :ARG_ IN) ; 

4 A questo punto e possibile inoltrare la richiesta: 

req->invoke() ; 

5 nfine, controllare eventuali errori e recuperare il risultato: 

if (req->env()->exception() ) 

// handle exception 
else 

{ 

CORBA: : Any _ptr pRetVal = req->result ( ) ->value ( ) ; 
CORBA: : float val; 
Any_ptr >>= val; 

} 

Per maggiori dettagli sull'utilizzo dell'interfaccia di chiamata dinamica, consultare il 
manuale VisiBroker Programmer's Guide. 



Collaudo di server CORBA 



C++Builder include un programma demo, di nome CORBATest, che genera un client 
universale il quale consente di collaudare le interfacce del server. CORBATest 
registra e esegue script che sollecitano gli oggetti nell'applicazione server CORBA. 

Se si pensa di utilizzare CORBATest per collaudare molti server, potrebbe risultare 
comodo installare questa applicazione nel menu Tools. Per fare cio, scegliere Tools I 
Configure Tools e aggiungere CorbaTest.exe utilizzando la finestra di dialogo Tools 
Options. 
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Configurazione dello strumento di collaudo 



Prima di poter utilizzare CORBATest per collaudare un'applicazione CORBA, si 
deve registrare interfaccia per il server con un Interface Repository in esecuzione. Per 
fare cio: 

1 Assicurarsi che lo SmartAgent di VisiBroker sia attivo scegliendo Tools I 
VisiBroker SmartAgent nel caso la voce di menu non abbia un segno di spunta. 

2 Eseguire l'applicazione server che si vuole collaudare. 

3 Scegliere Tools I IDL Repository per aggiungere i file .idl dell'applicazione server 
all'Interface Repository. Benche sia possibile utilizzare qualsiasi interface 
repository attivi, probabilmente si vorra utilizzare un repository dedicato al 
collaudo in modo che l'operazione non interferisca con altri usi dell'interface 
repository. Per awiare un repository dedicato al collaudo, fare clic sul pulsante 
Add IREP nella finestra di dialogo Update IDL Repository, che si richiama 
scegliendo il comando Tools I IDL Repository. 

4 Awiare lo strumento di collaudo mandando in esecuzione CORBATest.exe che e 
possibile generare a a partire dal codice sorgente del programma dimostrativo 
presente nella directory corbatest (.. \examples\corba\corbatest). 

Registrazione ed esecuzione di script di collaudo 



Uno script di collaudo e semplicemente una serie di metodi dell'oggetto CORBA da 
chiamare e di tutti i parametri che occorre passare a quei metodi. Un singolo script 
puo contenere varie chiamate alio stesso metodo (per esempio, per collaudare il 
metodo con valori di parametro diversi). 

La creazione di uno script awiene aggiungendo comandi al pannello dei comandi 
nella meta superiore del pannello presente nello strumento di colaudo. Per 
aggiungere un comando 

1 Se l'oggetto, di cui si desidera chiamare un metodo, non ha una pagina dedicata 
nel pannello degli oggetti (in alto a sinistra), scegliere il comando Edit I Add 
Object. Apparira una finestra di dialogo New Object, in cui e possibile selezionare 
un oggetto in base al suo repository ID. II repository ID di un oggetto e una stringa 
in formato "IDL:MyInterfacel:1.0", in cui "Mylnterface" e il nome dell'interfaccia 
cosi come e stata dichiarata nel file .IDL. Quando si seleziona un oggetto, si deve 
assegnargli un nome. 

2 Nella parte in alto a sinistra del pannello, selezionare la pagina dell'oggetto di cui 
si vuole aggiungere un metodo. Ogni pagina e identificata mediante un nome di 
oggetto, che e stato assegnato al momento dell'aggiunta dell'oggetto (passo 1). 
Ogni pagina elenca le operazioni (i metodi) dell'oggetto che e possibile collaudare. 

3 Aggiungere i comandi alio script trascinando un'operazione dal pannello oggetti 
al pannello dei comandi nella meta superiore del pannello dello strumento di 
collaudo. 
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4 Quando si seleziona un metodo nel pannello dei comandi, i parametri di input 
appaiono nel pannello dei dettagli in alto a destra. Immettere i valori per i 
parametri di input. La barra di stato indica il tipo di valore richiesto per il 
parametro di input corrente. 

Ripetete questi passi per aggiungere tutti i comandi desiderati per tutti gli oggetti 
desiderati. Non appena lo script contiene tutti i comandi desiderati, scegliere Edit I 
Save Script As (oppure fare clic sul pulsante Save Script) per salvare lo script e 
assegnargli un nome. A questo punto e possibile iniziare un nuovo script scegliendo 
il comando File I New Script (oppure facendo clic sul pulsante New Script). 

E possibile rimuovere gli oggetti o i comandi aggiunti a uno script selezionando 
l'oggetto oppure il comando e scegliendo l'opzione Edit I Remove Object oppure 
Edit I Remove Command. 

E possibile eseguire lo script scegliendo Run I Run, oppure facendo clic sul pulsante 
Run Script. Durante l'esecuzione dello script, lo strumento di collaudo utilizza 
l'interfaccia di chiamata dinamica per chiamare il server CORBA, passando i valori 
di parametro indicati. II valore di ritorno (se esiste) e tutti i parametri restituiti di tutti 
i metodi vengono quindi visualizzati nella sezione dei risultati dello strumento di 
collaudo (oppure in un file di risultati nel caso di collaudo automatico). 

La sezione dei risultati visualizza il risultato di tutti i comandi dello script sulla 
pagina Results. Questi stessi risultati appaiono anche sulle altre pagine della sezioni 
dei risultati, suddivisi in categorie, in modo da consentire di individuare 
rapidamente le informazioni desiderate. Le altre pagine della sezione dei risultati 
includono i valori di ritorno, i valori dei parametri di input, i valori dei parametri di 
output, e gli eventuali errori verificatisi durante l'esecuzione dello script. 
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Creazione di applicazioni server per 

Internet 

Le applicazioni per server Web estendono le funzioni e le capacita dei server Web 
esistenti. Un'applicazione per server Web riceve i messaggi di richiesta HTTP dal 
server Web, compie tutte le azioni richieste in quei messaggi e formula le risposte che 
restituisce al server Web. Tutte le operazioni che e possibile compiere con 
un'applicazione C++Builder possono essere incorporata in un'applicazione per 
server Web. 

C++Builder fornisce due architetture diverse per lo sviluppo di applicazioni per Web 
server: Web Broker e WebSnap. Benche queste due architetture siano diverse, 
WebSnap e Web Broker hanno molti elementi comuni. L'architettura WebSnap agisce 
come un superset di Web Broker. Fornisce componenti aggiuntivi e nuove funzioni 
come Preview tab Designer- che permette di visualizzare il contenuto di una pagina 
senza che lo sviluppatore debba eseguire l'applicazione. Le applicazioni sviluppate 
con WebSnap possono includere componenti Web Broker, mentre le applicazioni 
sviluppate con Web Broker non possono includere componenti WebSnap. 

Questo capitolo descrive le caratteristiche delle tecnologie Web Broker e WebSnap e 
fornisce le informazioni generali sulle applicazioni client /server basate su Internet. 

Web Broker e WebSnap 



Una delle funzioni di una qualsiasi applicazione e quella di rendere i dati accessibili 
agli utenti. In un'applicazione standard C++Builder cio viene fatto creando elementi 
di interfaccia tradizionali, come finestre di dialogo e finestre con scorrimento. Gli 
sviluppatori possono specificare la disposizione esatta di questi oggetti utilizzando i 
soliti strumenti di progettazione schede di C++Builder. Le applicazioni per Web 
server devono essere pero progettate in modo differente. Tutte le informazioni 
passate agli utenti devono essere sotto forma di pagine HTML trasferite tramite 
HTTP. Le pagine vengono generalmente interpretate sulla macchina client da 
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un'applicazione Web browser, che visualizza le pagine in una forma appropriata per 
il particolare sistema dell'utente nel suo stato attuale. 

II primo passo nella costruzione di un'applicazione per Web server consiste nello 
scegliere quale architettura si vuole utilizzare, Web Broker o WebSnap. Entrambi gli 
approcci forniscono molte funzioni simili, tra cui 

• II supporto per applicazioni di tipo CGI e Apache DSO Web server. Questi tipi 
sono descritti in "Tipi di applicazioni per server Web" a pagina 32-7. 

• Supporto per il multithreading per far si che le richieste in arrivo dei client 
vengano gestite su thread separati. 

• Cache dei moduli Web per risposte piu rapide. 

• Sviluppo multipiattaforma. L'applicazione per Web server e facilmente portabile 
tra i sistemi operativi Windows e Linux. II codice sorgente sara compilato sull'una 
o l'altra piattaforma. 

Sia i componenti Web Broker che WebSnap gestiscono tutti i meccanismi di 
trasferimento delle pagine. WebSnap utilizza Web Broker come cardine e pertanto 
incorpora tutte le funzionalita dell'architettura Web Broker. Tuttavia WebSnap offre 
un set di strumenti molto piu potente per la generazione delle pagine. Inoltre, in fase 
di esecuzione, le applicazioni WebSnap permettono di utilizzare script lato server 
come ausilio nella generazione delle pagine. Web Broker non ha questa possibility di 
scripting. Gli strumenti offerti in Web Broker non sono affatto completi come quelli 
in WebSnap e sono molto meno intuitivi. Se si sta sviluppando una nuova 
applicazione per Web server, probabilmente WebSnap rappresenta una scelta 
architetturale migliore rispetto a Web Broker. 

Le differenze principali fra questi due approcci sono descritte nella seguente tabella: 

Tabella 32.1 Web Broker e WebSnap 
Web Broker WebSnap 



Compatibile con versioni precedenti 



In un'applicazione e consentito un solo 
modulo Web. 



Nell'applicazione e consentito un solo 
dispatcher Web. 

I componenti specializzati per la creazione 
di contenuti includono produttori di pagine, 
componenti InternetExpress e componenti 
Web Services. 

Nessun supporto per scripting. 



Benche le applicazioni WebSnap possano 
utilizzare qualsiasi componente Web Broker che 
produce contenuti, i moduli Web e il dispatcher 
che li contengono sono nuovi. 

Piu moduli Web possono suddividere 
l'applicazione in unita, consentendo a piu 
sviluppatori di lavorare alio stesso progetto con 
meno conflitti. 

Piu dispatcher specializzati gestiscono vari tipi di 
richieste. 

Supporta tutti i produttori di contenuti che 
possono apparire in applicazioni Web Broker, 
oltre a molti altri progettati per consentire la 
generazione rapida di pagine web complesse data- 
driven. 

II supporto per scripting lato server (JScript o 
VBscript) consente di tenere separata la logica di 
generazione dell'HTML dalla logica di gestione. 
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WebSnap 



Tabella 32.1 Web Broker e WebSnap 
Web Broker 

Nessun supporto interno per pagine con 
nome. 

Nessun supporto per le sessioni. 



Ogni richiesta deve essere gestita 
esplicitamente, utilizzando o un elemento di 
azione o un componente di auto 
smistamento. 

Solo alcuni componenti specializzati 
forniscono un'anteprima del contenuto da 
essi prodotto. La maggior parte dello 
sviluppo non e visuale. 



Le pagine con nome possono essere 
automaticamente ottenute da un dispatcher di 
pagine e indirizzate da uno script sul lato server. 

Le sessioni memorizzano le informazioni 
necessarie relative a un utente per un breve 
periodo di tempo. Q6 puo essere utilizzato per 
attivita quali il supporto per operazioni di login/ 
logout. 

I componenti dispatcher rispondono 
automaticamente a una vasta gamma di richieste. 



WebSnaplets permette di costruire pagine web in 
modo piu visuale e di visualizzare il risultato in 
fase di progettazione. Le anteprime sono 
disponibili per tutti i componenti. 



Per ulteriori informazioni su Web Broker, vedere il Capitolo 33, "Utilizzo di Web 
Broker". Per ulteriori informazioni su WebSnap, consultare il Capitolo 34, 
"Creazione di applicazioni Web Server con WebSnap". 



Terminologia e standard 



La maggior parte dei protocolli che controllano le attivita in Internet e definita nei 
documenti Request for Comment (RFC) che vengono creati e mantenuti 
costantemente aggiornati dall'Internet Engineering Task Force (IETF), l'esercito di 
progetto e sviluppo di protocolli per Internet. Esistono molti RFC importanti 
risulteranno molto utili durante la scrittura di applicazioni per Internet: 

• RFC822, "Standard for the format of ARPA Internet text messages," descrive la 
struttura e contenuto degli header dei messaggi. 

• RFC1521, "MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms 
for Specifying and Describing the Format of Internet Message Bodies," descrive il 
metodo usato per incapsulare e trasportare messaggi multiparte e multiformato 
messages. 

• RFC1945, "Hypertext Transfer Protocol — HTTP /1.0," descrive un meccanismo di 
trasferimento usato per distribuire documenti ipermediali in gruppi di lavoro. 

Lo IETF conserva una libreria di documenti RFC nel proprio sito Web, 

www.ietf.cnri .res ton. va. us 
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Parti di uno Uniform Resource Locator 



Lo Uniform Resource Locator (URL) e una descrizione completa dell'ubicazione di 
una risorsa disponibile sulla rete. E composto da molte parti a cui puo accedere 
un'applicazione. Queste parti sono illustrate nella Figura 32.1: 

Figura 32.1 Parti di uno Uniform Resource Locator 

Host ScriptName Pathlnfo Query 



http://www.Tsite.com/art/gallery.dll/mammals?animal=dog&color=black 

i i i i 

Query Field Query Field 

La prima porzione (che tecnicamente non fa parte dell'URL) identifica il protocollo 
(http). Questa porzione puo specificare altri protocolli come https (http sicuro), ftp, e 
cosi via. 

La porzione Host identifica la macchina su cui e in esecuzione il server web e 
l'applicazione Web server. Sebbene non sia mostrato nella figura precedente, questa 
porzione puo ridefinire la porta che riceve i messaggi. Di solito, non e necessario 
specificare una porta, poiche il numero di porta e implicito nel protocollo. 

La porzione NomeScript specifica il nome dell'applicazione Web server. Questa e 
l'applicazione a cui il server web passa i messaggi. 

Dopo il nome dell'applicazione e specificata la porzione Pathinfo. Questa porzione 
identifica la destinazione del messaggio all'intemo dell'applicazione Web server. I 
valori delle informazioni di percorso possono contenere nomi di directory sulla 
macchina host, nomi di componenti che rispondono a messaggi specifici o qualsiasi 
altro meccanismo utilizzato dall'applicazione Web server per ripartire l'elaborazione 
di messaggi in ingresso. 

La porzione Query contiene una serie un valori con nome. Questi valori e i rispettivi 
nomi sono definiti dall'applicazione Web server. 

URI e. URL 

Lo URL e un sottoinsieme dello Uniform Resource Identifier (URI) definito nel 
documento relativo agli standard di HTTP, RFC1945. Le applicazioni per server Web 
spesso producono documenti a partire da varie sorgenti; il risultato finale non risiede 
in una particolare ubicazione ma e creato all'occorrenza. Gli URI possono descrivere 
risorse che non hanno una ubicazione specifica. 

Informazioni dell'header della richiesta HTTP 



I messaggi di richiesta HTTP contengono vari header che descrivono le informazioni 
sul client, la destinazione della richiesta, il modo in cui dovrebbe essere gestita e gli 
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eventuali contenuti spediti con la richiesta. Ogni header e identificato da un nome, 
come, ad esempio, "Host" seguito da un valore di stringa. Per esempio, si esamini la 
seguente richiesta HTTP: 

GET /art/gallery. dll/animals?animal=dog&color=black HTTP/1.0 

Connection: Keep-Alive 

User-Agent: Mozilla/3 . 0b4Gold (WinNT; I) 

Host: www.TSite.com:1024 

Accept: image/gif, image /x-xbitmap, image/jpeg, image/pjpeg, */* 

La prima riga identifica la richiesta come una GET. Un messaggio di richiesta GET 
chiede all'applicazione per server Web di restituire i contenuti associati alio URI 
indicato dopo la parola GET (in questo caso /art/ gallery.dll / 
animals?animal=doc&color=black). L'ultima parte della prima riga indica che il 
client sta utilizzando il protocollo HTTP 1.0 standard. 

La seconda riga e lo header della connessione e indica che la connessione non 
dovrebbe essere chiusa finche la richiesta non e stata assolta. La terza riga e lo header 
dello User- Agent e fornisce informazioni sul programma che ha generato la richiesta. 
La riga successiva e lo header dell'Host e fornisce le informazioni sul nome dell'host 
e sulla porta sul server che e stata contattata per stabilire la connessione. L'ultima 
riga e lo header di accettazione che elenca i tipi di supporto che il client e in grado di 
accettare come risposte valide. 

Attivita di un server HTTP 



La natura client /server dei browser per Web e ingannevolmente semplice. Per la 
maggior parte degli utenti, il recupero di informazioni sul World Wide Web e una 
procedura semplice: e sufficiente fare clic su un collegamento per far apparire sullo 
schermo le informazioni. Gli utenti un po' piu smaliziati hanno alcune nozioni sulla 
sintassi HTML e sulla natura client /server dei protocolli usati. Cio di solito e 
sufficiente per la produzione di semplici contenuti, orientati alia pagina, per siti Web. 
Gli autori di pagine Web piu complesse hanno un'ampia gamma di opzioni per 
automatizzare la raccolta e la presentazione di informazioni usando HTML. 

Prima di generare un'applicazione per server Web, e utile capire in che modo il client 
formula una richiesta e il modo in cui il server risponde alle richieste del client. 

Composizione delle richieste del client 



Quando si seleziona un collegamento ipertestuale HTML (oppure l'utente specifica 
un URL), il browser raccoglie le informazioni relative al protocollo, al dominio 
specificato, al percorso per raggiungere le informazioni, sulla data e l'ora, 
sull'ambiente operative sullo stesso browser e su altri contenuti informativi. Quindi 
compone una richiesta. 

Per esempio, per visualizzare una pagina di immagini basata sul criterio selezionato 
facendo clic sui pulsanti di una scheda, il client costruirebbe questo URL: 

http: //www. TSite.com/ art /gallery .dll/animals?animal=dog&color=black 
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che specifica un server HTTP nel dominio www.TSite.com. II client contatta 
www.TSite.com, si connette al server HTTP e gli passa una richiesta. La richiesta 
potrebbe essere simile alia seguente: 

GET /art/gallery. dll/animals?animal=dog&color=black HTTP/1.0 

Connection: Keep-Alive 

User-Agent: Mozilla/3 . Ob4Gold (WinNT; I) 

Host: www.TSite.com:1024 

Accept: image/gif, image /x-xbitmap, image/jpeg, image/pjpeg, */* 

Soddisfacimento delle richieste del client 



II server Web riceve una richiesta del client e potrebbe eseguire qualsiasi numero di 
azioni, in base alia sua configurazione. Se il server e configurato per riconoscere come 
un programma la porzione / gallery.dll della richiesta, esso passa le informazioni 
sulla richiesta a tale programma. II modo in cui vengono passate al programma le 
informazioni sulla richiesta dipendono dal tipo di applicazione per server Web: 

• Se il programma e un programma Common Gateway Interface (CGI), il server 
passa le informazioni contenute nella richiesta direttamente al programma CGI. II 
server resta in attesa mentre il programma viene eseguito. Quando il programma 
CGI termina, esso restituisce i contenuti direttamente al server. 

• Se il programma e WinCGI, il server apre un file, vi scrive le informazioni della 
richiesta. Quindi esegue il programma Win-CGI, passandogli l'ubicazione del file 
che contiene le informazioni del client e l'ubicazione di un file che il programma 
Win-CGI dovrebbe usare per creare i contenuti. II server resta in attesa mentre il 
programma viene eseguito. Quando il programma termina, il server legge i dati 
dal file di contenuti scritto dal programma Win-CGI. 

• Se il programma e una dynamic-link library (DLL), il server carica la DLL (se 
occorre) e passa le informazioni contenute nella richiesta alia DLL sotto forma di 
dato di tipo structure. II server resta in attesa mentre il programma viene eseguito. 
Quando la DLL termina, essa restituisce il contenuto direttamente al server. 

In tutti i casi, il programma agisce in base alia richiesta e compie le azioni specificate 
dal programmatore: accede ai database, esegue semplici consultazioni di tabella o 
calcoli, genera o seleziona documenti HTML e cosi via. 

Risposta alle richieste del client 



Dopo aver esaudito una richiesta del client, ogni applicazione per server Web genera 
una pagina di codice HTML o un altro contenuto MIME e lo restituisce (tramite il 
server) al client per visualizzarlo. Anche il modo in cui viene trasmessa la risposta e 
differente, a seconda del tipo di programma: 

• Quando un script Win-CGI termina, esso costruisce una pagina HTML, la scrive in 
un file, scrive tutte le informazioni di risposta in un altro file e restituisce al server 
le ubicazioni di entrambi i file. II server apre entrambi i file e restituisce al client la 
pagina HTML. 
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• Quando una DLL termina, essa restituisce direttamente la pagina HTML e tutte le 
informazioni di risposta al server il quale, a sua volta, le restituisce al client. 

La creazione di un'applicazione per server Web come DLL riduce il carico di sistema 
e l'utilizzo delle risorse riducendo il numero dei processi e degli accessi a disco 
necessari per soddisfare una singola richiesta. 

Tipi di applicazioni per server Web 



Sia che si utilizzi Web Broker o WebSnap, e possibile creare cinque tipi standard per 
Web server. Inoltre, e possibile creare un eseguibile Web Application Debugger, che 
integra il server Web nell'applicazione in modo che sia possibile eseguire il debug 
della logica dell'applicazione. L'eseguibile Web Application Debugger e destinato 
solo al debug. Quando si distribuisce l'applicazione, si dovrebbe convertirla in uno 
degli altri cinque tipi. 

ISAPI e NSAPI 

Un'applicazione ISAPI o NSAPI per server Web e una DLL che viene caricata dal 
server Web. Le informazioni della richiesta del client vengono passate alia DLL come 
una struttura e vengono valutate dall'applicazione ISAPI/NSAPI, che crea la 
richiesta appropriata e gli oggetti di risposta. Ogni messaggio di richiesta viene 
gestito automaticamente in un thread di esecuzione separato. 

CGI indi pendente 

Un'applicazione CGI indipendente per server Web e un'applicazione per consolle 
che riceve le informazioni della richiesta del client sullo standard input e restituisce i 
risultati al server sullo standard output. Questi dati vengono valutati 
dall'applicazione CGI, che crea la richiesta appropriata e gli oggetti di risposta. Ogni 
messaggio di richiesta viene gestito da un'istanza differente dell'applicazione. 

Win-CGI indipendente 

Un'applicazione Win-CGI indipendente per server Web e un'applicazione Windows 
che riceve le informazioni della richiesta del client da un file di impostazioni di 
configurazione (INI) scritto dal server e scrive i risultati in un file che il server 
restituisce al client. II file INI viene valutato dall'applicazione del Web server, che 
crea la richiesta appropriata e gli oggetti di risposta. Ogni messaggio di richiesta 
viene gestito da un'istanza differente dell'applicazione. 

Apache 

Un'applicazione Apache per server Web e una DLL che viene caricata dal server 
Web. Le informazioni della richiesta del client vengono passate alia DLL come una 
struttura e vengono valutate dall'applicazione Apache del Web server, che crea la 
richiesta appropriata e gli oggetti di risposta. Ogni messaggio di richiesta viene 
gestito automaticamente in un thread di esecuzione separato. 

Quando si distribuisce l'applicazione per Web server Apache, sara necessario 
specificare nei file di configurazione di Apache alcune informazioni specifiche per 
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l'applicazione. II nome del modulo predefinito e il nome del progetto a cui viene 
aggiunto il suffisso _module. Ad esempio, il nome del modulo di un progetto di nome 
Projectl dovrebbe essere Projectl jnodule. Analogamente, il tipo di contenuto 
predefinito e il nome del progetto a cui viene aggiunto -content, e il tipo di gestore 
predefinito e il nome del progetto a cui viene aggiunto -handler. 

Se occorre, queste definizioni possono essere modificate nel file di progetto (.bpr). Ad 
esempio, quando si crea il progetto nel file di progetto viene memorizzato un nome 
di modulo predefinito. Ecco un tipico esempio: 

extern "C" 

{ 

Httpd: :module __declspec (dllexport ) Projectljnodule; 

} 

Se si cambia nome al progetto durante il processo di salvataggio, quel nome non 
viene automaticamente modificato. Ogni volta che si rinomina il progetto, e 
necessario modificare il nome del modulo nel file di progetto in modo che 
corrisponda al nome del progetto. Le definizioni del contenuto e del gestore 
dovrebbero cambiare automaticamente una volta che il nome del modulo viene 
modificato. 

Per informazioni sull'utilizzo nei file di configurazione Apache delle definizioni di 
modulo, contenuto e gestore, vedere la documentazione sul sito Web di Apache 
httpd.apache.org. 

Web App Debugger 

I tipi di server summenzionati presentano vantaggi e svantaggi per gli ambienti di 
siluppo, ma nessuno di loro e particolarmente adatto per eseguire il debug. La 
distribuizione dell'applicazione e la configurazione del debugger puo rendere il 
debug dell'applicazione per Web server un'operazione di gran lunga piu noiosa 
rispetto al debug di altri tipi di applicazione. 

Per fortuna, il debug di un'applicazione per Web server non e necessariamente cosi 
complessa. C++Builder include un Web App Debugger che semplifica le operazioni 
di debug. Web App Debugger agisce sulla macchina di sviluppo come un server 
Web. Se si esegue il build dell'applicazione per Web server come un eseguibile di 
Web App Debugger, la distribuzione viene portata a termine in automatico durante il 
processo di build. Per eseguire il debug dell'applicazione, e sufficiente avviarla 
mediante il comando Run I Run. Poi, selezionare Tools I Web App Debugger, fare clic 
sull'URL predefinito e selezionare l'applicazione nel browser Web che viene 
visualizzato. L'applicazione verra avviata nella finestra del browser e sara possibile 
utilizzare l'IDE per impostare i breakpoint e ottenere le informazioni di debug. 

Non appena l'applicazione sara pronta per essere collaudata o distribuita in un 
ambiente di produzione, sara possibile convertire il progetto Web App Debugger in 
uno degli altri tipi di destinazione utilizzando la procedura discritta di seguito. 

Quando si crea un progetto Web App Debugger, sara necessario fornire al progetto 
un CoClass Name. Questo e semplicemente un nome utilizzato da Web App 
Debugger per fare riferimento all'applicazione. Quasi tutti gli sviluppatori utilizzano 
come CoClass Name il nome dell'applicazione. 
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Conversione del tipo di destinazione per applicazioni Web server 



Una potente funzionalita di Web Broker e WebSnap e costituita dal fatto che essi 
offrono vari tipi di server di destinazione. C++Builder consente di eseguire 
facilmente la conversione da un tipo di destinazione a un altro. 

Poiche Web Broker e WebSnap hanno filosofie di progettazione leggermente 
differenti, e necessario utilizzare un diverso metodo di conversione per ogni 
architettura. Per convertire il tipo di destinazione dell'applicazione Web Broker, fare 
quanta segue: 

1 Fare clic destro sul modulo Web e scegliere il comando Add To Repository. 

2 Nella finestra di dialogo Add To Repository, assegnare al modulo Web un titolo, 
una descrizione di testo, la pagina del Repository (probabilmente Data Modules), 
un nome di autore e un'icona. 

3 Scegliere OK per salvare il modulo Web come modello. 

4 Dal menu principale, scegliere il comando File I New e selezionare l'opzione Web 
Server Application. Nella finestra di dialogo New Web Server Application 
scegliere il tipo di destinazione opportuno. 

5 Cancellare il modulo Web generato automaticamente. 

6 Dal menu principale, scegliere il comando File I New e selezionare il modello 
salvato al punto 3. II modello sara presente nella pagina specificata al punto 2. 

Per convertire il tipo di destinazione di un'applicazione WebSnap: 

1 Caricare un progetto nell'IDE. 

2 Visualizzare Project Manager utilizzando il comando View I Project Manager. 
Espandere il progetto in modo da rendere visibili tutte le unit. 

3 In Project Manager, fare clic sul pulsante New per creare un nuovo progetto di 
applicazione per Web server. Fare doppio clic nella pagina WebSnap 
sull'elemento WebSnap Application. Selezionare le opzioni appropriate per il 
progetto, compreso il tipo server che si desidera utilizzare, quindi fare clic su OK. 

4 Espandere il nuovo progetto in Project Manager. Selezionare tutti i file visualizzati 
e cancellarli. 

5 Uno alia volta, selezionare ogni singolo file nel progetto (tranne il file di scheda in 
progetto Web App Debugger) e trascinarlo sul nuovo progetto. Appena appare 
una finestra di dialogo che chiede se si desidera aggiungere quel file al nuovo 
progetto, fare clic su Yes. 

Debug di applicazioni server 



II debug di applicazioni per server Web presenta alcuni problemi specifici, perche 
esse vengono eseguite per rispondere a messaggi provenienti da un server Web. Non 
e possibile lanciare semplicemente l'applicazione dall'IDE, perche cosi facendo si 
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lascia il server Web fuori dal ciclo e l'applicazione non trovera il messaggio di 
richiesta che si aspettava. 

Gli argomenti successivi descrivono le tecniche utilizzabili per eseguire il debug di 
applicazioni per Web server. 



Utilizzo di Web Application Debugger 



Web Application Debugger permette di controllare in modo modo semplice le 
richieste HTTP, le risposte e i tempi di risposta. II Web Application Debugger 
sostituisce il server Web. Una volta eseguito il debug dell'applicazione, e possibile 
convertirla in uno dei tipi supportati di applicazione Web e installarla in un server 
Web commerciale. 

Per utilizzare Web Application Debugger, e necessario per prima cosa creare 
l'applicazione Web come un eseguibile Web Application Debugger. Sia che si utilizzi 
Web Broker o WebSnap, il wizard che crea l'applicazione per Web server include 
questa possibility come un'opzione da selezionare non appena si inizia 
l'applicazione. In questo modo viene creata un'applicazione per Web server che e 
anche un server COM. 

Per informazioni su come scrivere questa applicazione per Web server utilizzando 
Web Broker, vedere il Capitolo 33, "Utilizzo di Web Broker". Per ulteriori 
informazioni sull'utilizzo di WebSnap, vedere il Capitolo 34, "Creazione di 
applicazioni Web Server con WebSnap". 



Awio dell'applicazione con Web Application Debugger 

Una volta sviluppata l'applicazione per Web server, e possibile eseguirla e fame il 
debug nel seguente modo: 

1 Caricato il progetto nell'IDE, impostare tutti i breakpoint in modo che sia possibile 
fare il debug dell'applicazione esattamente come con qualsiasi altro eseguibile. 

2 Scegliere il comando Run I Run. Viene visualizzata la finestra della console del 
server COM che e l'applicazione per Web server. La prima volta che si esegue 
l'applicazione, il server COM viene registrato in modo che il Web Application 
debugger vi possa accedere. 

3 Selezionare il comando Tools I Web App Debugger. 

4 Fare clic sul pulsante Start. Viene visualizzata la pagina Serverlnfo nel Browser 
predefinito. 

5 La pagina Serverlnfo contiene una lista a discesa di tutti gli eseguibili Web 
Application Debugger registrati. Selezionare l'applicazione dall'elenco a discesa. 
Se l'applicazione non e presente in questa lista a discesa, provare a eseguire 
l'applicazione come un normale eseguibile. L'applicazione deve essere eseguita 
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almeno una volta in modo che possa effettuare la registrazione. Se anche dopo 
questa operazione l'applicazione non e inclusa nella lista a discesa, provare ad 
aggiornare la pagina web. (A volte il browser Web memorizza questa pagina nella 
cache, impedendo di vedere le modifiche piu recenti.) 

6 Dopo aver selezionato l'applicazione nella lista a discesa, fare clic sul pulsante Go. 
In questo modo si avvia l'applicazione nel Web Application Debugger, il quale 
fornisce i dettagli relativi ai messaggi di richiesta e di risposta che passano fra 
l'applicazione e il Web Application Debugger. 

Conversione dell'applicazione in un altro tipo di applicazione per Web server 

Terminate il debug dell'applicazione per Web server con Web Application 
Debugger, sara necessario convertirla in un altro tipo di applicazione Web che pud 
essere installata su un server Web commerciale. Per maggiori informazioni sulla 
conversione delle proprie applicazioni, consultare "Conversione del tipo di 
destinazione per applicazioni Web server" a pagina 32-9. 



Debug di applicazioni Web sotto forma di DLL 



Le applicazioni ISAPI, NSAPI, e Apache sono in effetti DLL che contengono punti 
d'ingresso predefiniti. II server Web passa i messaggi di richiesta all'applicazione 
facendo chiamate a questi punti d'ingresso. Poiche queste applicazioni sono DLL, e 
possibile eseguirne il debug impostando i parametri di esecuzione dell'applicazione 
per avviare il server. 

Per configurare i parametri di esecuzione dell'applicazione, scegliere il comando 
Run I Parameters e impostare Host Application e il Run Parameters in modo da 
specificare l'eseguibile per il server Web e tutti i parametri necessari nel momento in 
cui lo si avvia. Per maggiori informazioni sui valori per il proprio server Web, 
consultare la documentazione fornita dal produttore del Web Server. 

Per alcuni Web Servers e necessario apportare ulteriori modifiche prima che si abbia 
il diritto di avviare l'Host Application in questo modo. Per i dettagli, consultare la 
documentazione fornita dal produttore del Web Server. 




Se si utilizza Windows 2000 con IIS 5, i dettagli su tutte le modifiche che e necessario 
apportare per configurare correttamente i diritti sono descritte sul sito Web seguente: 



http://community.borland.eom/article/0, 1410, 23024, 00. html 

Una volta configurate le opzioni Host Application e Run Parameters, e possibile 
configurare i breakpoint in modo che, non appena il server passa un messaggio di 
richiesta alia DLL, uno di questi breakpoint venga intercettato e si possa eseguire il 
debug normalmente. 

Prima di avviare il server Web usando i parametri di esecuzione dell'applicazione, 
assicurarsi che il server non sia gia in esecuzione. 
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Debug di applicazioni server 



Diritti utente necessari per il debug di DLL 

In ambiente Windows, si devono avere i diritti di utenza adeguati per eseguire il 
debug di una DLL. E possibile ottenere i diritti nel seguente modo: 

1 Nella parte Administrative Tools del Control Panel, fare clic su Local Security 
Policy. Espandere Local Policies e fare doppio clic su User Rights Assignment. 
Fare doppio clic sull'opzione Act as part of the operating system nella parte destra 
del pannello. 

2 Selezionare Add per aggiungere un utente all'elenco. Aggiungere l'utente 
corrente. 

3 Riavviare il sistema in modo da rendere operative le modifiche. 
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Utilizzo di 



Web Broker 



I componenti di Web Broker (situati sulla pagina Internet della Component palette) 
permettono di creare gestori di evento che sono associati a uno specifico Uniform 
Resource Identifier (URI). A elaborazione conclusa, e possibile impostare da 
programma documenti HTML o XML e trasferirli al client. I componenti WEb Broker 
si possono utilizzare per lo sviluppo di applicazioni per piu piattaforme. 

Spesso, il contenuto delle pagine web e tratto da dei database. E possibile utilizzare 
dei componenti Internet per gestire automaticamente le connessioni ai database, il 
che consente a un singolo DLL di gestire numerose connessioni database thread-safe. 

Nelle prossime sezioni di questo capitolo viene spiegato come si usano i componenti 
Web Broker per creare un'applicazione per Web server. 



Creazione di applicazioni per Web server con Web Broker 



Per creare una nuova applicazione per Web server utilizzando l'architettura Web 
Broker: 

1 Selezionare File I New I Other. 

2 Nella finestra di dialogo New Items, selezionare la pagina New e scegliere Web 
Server Application. 

3 Viene visualizzata una finestra di dialogo, dove e possibile selezionare uno dei tipi 
di applicazione Web server: 

• ISAPI and NSAPI: Selezionando questo tipo di applicazione si configura il 
progetto come un DLL, con i metodi esportati previsti dal Web server. Include 
inoltre i file header appropriati per la generazione dell'applicazione. 

• Apache: Selezionando questo tipo di applicazione si configura il progetto come un 
DLL, con i metodi esportati previsti dal Web server Apache. Include inoltre i file 
header appropriati per la generazione dell'applicazione. 
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• CGI stand-alone: La selezione di questo tipo di applicazione imposta il progetto 
come un'applicazione per console e include i file header appropriati. 

• Win-CGI stand-alone: La selezione di questo tipo di applicazione imposta il 
progetto come un'applicazione per Windows e include i file header appropriati. 

• Web Application Debugger stand-alone executable: La selezione di questo tipo di 
applicazione configura un ambiente per sviluppare e provare applicazioni per 
Web server. Questo tipo di applicazione non e destinato all'impiego. 

Scegliere il tipo di Web Server Application capace di comunicare con il tipo di Web 
Server che l'applicazione utilizzera. In questo modo, si crea un nuovo progetto 
configurato per utilizzare i componenti Internet e contenente un modulo Web vuoto. 

II modulo Web 



II modulo Web (TWebModule) e un discendente di TDataModule e puo essere 
utilizzato nello stesso modo: fornire il controllo centralizzato delle regole di gestione 
e dei componenti non visuali nell'applicazione Web. 

Si aggiunge poi qualsiasi produttore di contenuti che l'applicazione utilizza per 
generare messaggi di risposta. Questi possono essere i produttori di contenuti 
incorporati, come TPageProducer, TDataSetPageProducer, TDataSetTableProducer, 
TQueryTableProducer e TInetXPageProducer oppure discendenti realizzati ad hoc di 
TCustomContentProducer. Se l'applicazione genera messaggi di risposta comprendenti 
materiale tratto da database, si possono aggiungere componenti di accesso ai dati o 
componenti speciali per scrivere un Web server che si comporti da cliente in 
un'applicazione per database multi-tier. 

Oltre registrare i componenti non visuali e le regole di gestione, il modulo Web 
agisce anche come dispatcher, e fa corrispondere i messaggi di richiesta HTTP in 
arrivo a elementi di azione che generano le risposte alle richieste. 

A volte, si dispone gia di un modulo dati contenente molti dei componenti e delle 
regole di gestione non visuali che si intend ono usare nell'applicazione Web. E 
possibile sostituire il modulo Web con il proprio modulo dati preesistente. E 
sufficiente cancellare il modulo Web generato automaticamente e sostituirlo con il 
proprio modulo dati. Quindi, si aggiunge al modulo dati un componente 
TWebDispatcher, in modo che possa eseguire il dispatch di messaggi di richiesta a 
elementi di azione, secondo le modalita previste per i moduli Web. Se si desidera 
modificare il modo in cui gli elementi di azione sono selezionati per rispondere a 
messaggi di richiesta HTTP in arrivo, far derivare un nuovo componente dispatcher 
da TCustomWebDispatcher e aggiungerlo al modulo dati al posto dell'altro. 

II progetto puo contenere solamente un dispatcher. Questo puo essere sia il modulo 
Web generato automaticamente quando si crea il progetto, sia il componente 
TWebDispatcher aggiunto a un modulo dati in sostituzione del modulo Web. Se in 
fase di l'esecuzione si crea un secondo modulo dati contenente un dispatcher, 
l'applicazione per Web server genera un errore di esecuzione. 

II modulo Web impostato in fase di progetto e in effetti un modello. Nelle 
applicazioni ISAPI e NSAPI, ogni messaggio di richiesta genera un thread distinto e 
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per ogni thread vengono create dinamicamente ricorrenze distinte del modulo Web e 
del suo contenuto. 

II modulo Web di un'applicazione per Web server basata su DLL viene messo in 
cache per migliorare il tempo di risposta quando viene riutilizzato. Lo stato del 
dispatcher e della sua lista di azioni non viene reinizializzato tra due richieste 
successive. L'attivazione o la disattivazione di elementi di azione in fase di 
esecuzione puo produrre risultati inattesi, quando il modulo e utilizzato per 
successive richieste client. 



L'oggetto Application Web 



II progetto configurato per l'applicazione Web contiene una variabile globale 
chiamata Application. Application e un discendente di TWeb Application 
(TIS API Application,! Apache Application o T CGI Application) adeguato al tipo di 
applicazione che si sta creando. Viene eseguito in risposta a messaggi di richiesta 
HTTP provenienti dal Web server. 

Nel file di progetto non includere Forms.hpp dopo l'istruzione include relativa a 
CGIApp.hpp o a ISAPIApp.hpp. Forms.hpp dichiara tra l'altro una variabile globale 
di nome Application, e se tale variabile appare dopo CGIApp.hpp o ISAPIApp.hpp, 
Application verra inizializzata a un oggetto di tipo errato. 
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Quando l'applicazione Web riceve un messaggio di richiesta HTTP, crea un oggetto 
TWebRequest che rappresenta il messaggio di richiesta HTTP e un oggetto 
TWebResponse per rappresentare la risposta da restituire. L'applicazione quindi passa 
questi oggetti al dispatcher Web (che puo essere il modulo Web o un componente 
TWebDispatcher) . 

II dispatcher Web controlla il flusso dell'applicazione per Web server. II dispatcher 
gestisce un assortimento di elementi di azione (TWebActionltem) che sanno come 
gestire certi tipi di messaggi di richiesta HTTP. II dispatcher identifica gli elementi di 
azione appropriati o i componenti auto-dispatching capaci di gestire il messaggio di 
richiesta HTTP e passa gli oggetti di richiesta e di risposta al gestore identificato per 
consentirgli di eseguire l'azione richiesta o di formulare un messaggio di risposta. 
Tutto cio viene spiegato in dettaglio nella sezione "II dispatcher Web" a pagina 33-4. 
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Figura 33.1 Struttura di un'applicazione server 
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Gli elementi di azione hanno la responsabilita di leggere la richiesta e di mettere 
insieme il messaggio di risposta. I produttori di contenuti specializzati affiancano gli 
elementi di azione nel generare dinamicamente il contenuto dei messaggi di risposta, 
che possono comprendere un codice HTML ad hoc, o altro contenuto MIME. I 
produttori di contenuti possono fare uso di altri produttori o discendenti di 
THTMLTagAttributes, per aiutarli a compilare il messaggio di risposta. Per maggiori 
informazioni sui produttori di contenuti, consultare "Generazione del contenuto dei 
messaggi di risposta" on pagina 33-14. 

Se si crea il Web Client in un'applicazione per database multi-tier, l'applicazione per 
Web server puo includere altri componenti auto-dispatching che rappresentano 
informazioni di database codificate in XML e classi di manipolazione di database 
codificate in javascript. Se si crea un server che implementa un Web Service, 
l'applicazione per Web server puo includere un componente auto-dispatching che 
passa messaggi basati su SOAP a un invoker che li interpreta e li esegue. II dispatcher 
invita i componenti auto-dispatching a gestire il messaggio di richiesta, dopo averci 
provato con tutti i suoi elementi di azione. 

Quando tutti gli elementi di azione (o i componenti per il dispatch automatico) 
hanno terminato di creare la risposta riempiendo l'oggetto TWebResponse, il 
dispatcher restituisce il risultato all'applicazione Web. L'applicazione trasmette la 
risposta al client tramite il server Web. 



II dispatcher Web 



Se si utilizza un modulo Web, questo agisce come un dispatcher Web. Se si utilizza 
un modulo dati esistente, bisogna aggiungervi un singolo componente dispatcher 
(TWebDispatcher). II dispatcher gestisce un assortimento di elementi di azione in 
grado di gestire certi tipi di messaggi di richiesta. Quando l'applicazione Web passa 
un oggetto di richiesta e un oggetto di risposta al dispatcher, seleziona anche uno o 
piu elementi di azione per rispondere alia richiesta. 
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Aggiunta di azioni al dispatcher 



Si apre Taction editor di Object Inspector facendo clic sui puntini di sospensione della 
proprieta Actions del dispatcher. Gli elementi di azione possono essere aggiunti al 
dispatcher facendo clic sul pulsante Add nell' Action editor. 

Si aggiungono azioni al dispatcher per rispondere a vari metodi di richiesta o agli 
URI di destinazione. Vi sono diversi modi di impostare gli elementi di azione. Si puo 
cominciare da quelli che preelaborano le richieste e terminano con un'azione 
predefinita che verifica se la risposta e completa e invia la risposta, oppure restituisce 
un codice di errore. Si puo anche aggiungere un elemento di azione distinto per ogni 
tipo di richiesta. In questo caso, ciascun elemento di azione gestisce 
indipendentemente la propria richiesta. 

Gli elementi di azione sono discussi dettagliatamente in "Elementi di azione" on 
pagina 33-6. 

Dispatch dei messaggi di richiesta 



Quando il dispatcher riceve la richiesta client, genera un evento BeforeDispatch. 
Questo da all'applicazione la possibility di preelaborare il messaggio di richiesta 
prima che sia visto da un elemento di azione. 

Quindi, il dispatcher cerca nell'elenco degli elementi di azione un elemento che 
coincida con la porzione Pathlnfo dell'URL di destinazione del messaggio di richiesta 
e che possa fornire il servizio specificato come metodo del messaggio di richiesta. 
Alio scopo, confronta le proprieta Pathlnfo e MethodType dell'oggetto TWebRequest 
con le proprieta dello stesso nome presenti nell'elemento di azione. 

Quando il dispatcher trova un elemento di azione appropriato, lo attiva. L' elemento 
di azione una volta attivato, fa una delle cose seguenti: 

• Compila il contenuto della risposta e lo invia, oppure segnala che la richiesta e 
completamente gestita. 

• Aggiunge qualcosa alia risposta e poi permette ad altri elementi di azione di 
completare il lavoro. 

• Passa la richiesta ad altri elementi di azione. 

Se, dopo avere controllato tutti i suoi elementi di azione, il messaggio non e stato 
gestito, il dispatcher controlla ogni componente auto-dispatching registrato in modo 
speciale che non utilizza elementi di azione. Questi componenti sono specifici per le 
applicazioni database multi-tiered e sono descritti nella sezione "Creazione di 
applicazioni Web con InternetExpress" a pagina 29-33 

Se, dopo avere controllato tutti gli elementi di azione e qualsiasi componente auto- 
dispatching registrato in modo speciale, il messaggio di richiesta non e stato ancora 
completamente gestito, il dispatcher chiama l'elemento di azione predefinito. 
L'elemento di azione predefinito non ha bisogno di corrispondere ne all'URL di 
destinazione ne al metodo della richiesta. 
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Quando il dispatcher ha raggiunto la fine della lista di azioni (tra cui l'azione 
predefinita, se prevista) e nessuna azione e stata attivata, al server non viene inviato 
nulla. II server si limita a interrompere la connessione con il client. 

Se la richiesta e gestita dagli elementi di azione, il dispatcher genera un evento 
AfterDispatch. Questo offre all'applicazione l'ultima opportunity di verificare la 
risposta fornita e di applicare modifiche all'ultimo minuto. 

Elementi di azione 



Ogni elemento di azione (TWebActionltem) esegue un'operazione specifica in risposta 
a un certo tipo di messaggio di richiesta. 

Gli elementi di azione possono rispondere completamente a una richiesta, o eseguire 
parte della risposta lasciando poi che siano altri elementi di azione a completare il 
lavoro. Gli elementi di azione possono inviare il messaggio HTTP di risposta alia 
richiesta, o semplicemente impostare una parte della risposta che viene poi 
completata da altri elementi di azione. Se una risposta e completata dagli elementi di 
azione ma non viene inviata, l'applicazione per Web server invia il messaggio di 
risposta. 

Determinazione dell'attivazione degli elementi di azione 



La maggior parte delle proprieta di un elemento di azione determinano quando il 
dispatcher lo seleziona per gestire un messaggio di richiesta HTTP. Per impostare le 
proprieta di un elemento di azione, e necessario attivare prima l'Action editor: si 
seleziona la proprieta Actions del dispatcher nell'Object Inspector e si fa clic sui 
puntini di sospensione. Quando un'azione e selezionata nell'Action editor, se ne 
possono modificare le proprieta nell'Object Inspector. 

L'URL di destinazione 

II dispatcher confronta la proprieta Pathlnfo di un elemento di azione con il Pathlnfo 
del messaggio di richiesta. II valore di questa proprieta dovrebbe essere la parte 
riguardante le informazioni di percorso dell'URL per tutte le richieste che l'elemento 
di azione e preparato a gestire. Ad esempio, dato questo URL: 

http: //www. TSite.com/art /gallery. dll/mammals?animal=dog&color=black 

e supponendo che la parte /gallery . dll indichi l'applicazione per Web server, la parte 
riguardante le informazioni di percorso e 

/mammals 

Le informazioni di percorso sono utili per indicare dove l'applicazione Web deve 
cercare le informazioni quando esegue le richieste o per dividere l'applicazione Web 
in sottoinsiemi logici. 
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La proprieta Method Type 

La proprieta MethodType di un elemento di azione indica quale tipo di messaggi di 
richiesta puo elaborare. II dispatcher confronta la proprieta MethodType di un 
elemento di azione al MethodType del messaggio di richiesta. MethodType puo 
assumere uno dei seguenti valori: 



Tabella 33.1 Valori di MethodType 




mtCet La richiesta chiede alle informazioni associate all'URI di destinazione di essere 

restituita in un messaggio di risposta. 

mtHead La richiesta richiede le proprieta dell'intestazione di una risposta, come se 
rispondesse a una richiesta mtGet, ma omettendo il contenuto della risposta. 

mtPost La richiesta fornisce informazioni da inviare all'applicazione Web. 

mtPut La richiesta chiede che la risorsa associata all'URI di destinazione sia sostituita dal 

contenuto del messaggio di richiesta. 

mtAny Corrisponde a qualsiasi tipo di metodo di richiesta, tra cui mtGet, mtHead, mtPut e 

mtPost. 



Attivazione e disattivazione di elementi di azione 

Ogni elemento di azione ha una proprieta Enabled che puo essere utilizzata per 
attivarlo o disattivarlo. Impostando Enabled a false, si disattiva l'elemento di azione 
facendo si che esso non venga preso in considerazione dal dispatcher quando ricerca 
un elemento di azione per gestire una richiesta. 

Un gestore di evento BeforeDispatch puo controllare quali elementi di azione devono 
elaborare una richiesta modificando la loro proprieta Enabled, prima che il dispatcher 
cominci a farli corrispondere al messaggio di richiesta. 

Modificare la proprieta Enabled durante l'esecuzione di un'azione puo determinare 
risultati inattesi nelle richieste successive. Se l'applicazione per Web server e un DLL 
che mette in cache i moduli Web, alia richiesta successiva non verra ripristinato lo 
stato iniziale. Per riportare tutti gli elementi di azione alio stato iniziale opportuno si 
utilizza l'evento BeforeDispatch. 

Scelta di un elemento di azione predefinito 

Solo uno degli elementi di azione puo essere l'elemento di azione predefinito. 
L'elemento di azione predefinito viene selezionato impostandone la proprieta Default 
a true. Quando la proprieta Default di un elemento di azione viene impostata a true, 
la proprieta Default del precedente elemento di azione predefinito (se previsto) viene 
impostata a false. 

Quando il dispatcher esamina la lista di elementi di azione per sceglierne uno che 
sappia gestire una richiesta, memorizza il nome dell'elemento di azione predefinito. 
Se la richiesta non e stata gestita completamente quando il dispatcher ha raggiunto la 
fine della lista di elementi di azione, viene eseguito l'elemento di azione predefinito. 

II dispatcher non controlla le proprieta Pathlnfo o MethodType dell'elemento di azione 
predefinito. II dispatcher non controlla neanche la proprieta Enabled. Pertanto, si puo 
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essere certi che l'elemento di azione predefinito venga chiamato solamente alia fine, 
impostandone la proprieta Enabled a false. 

L'elemento di azione predefinito dovrebbe essere preparato a gestire qualsiasi 
richiesta che incontra, anche se e solo per restituire un codice di errore indicante una 
URI o tin MethodType non validi. Se l'elemento di azione predefinito non gestisce la 
richiesta, nessuna risposta e inviata al client Web. 

Modificare la proprieta Default di un'azione durante l'esecuzione potrebbe produrre 
risultati inattesi per la richiesta corrente. Se la proprieta Default di un'azione gia 
attivata e impostata a true, l'azione non viene riesaminata e il dispatcher non la attiva 
nuovamente quando raggiunge la fine della lista di azioni. 

Risposta a messaggi di richiesta mediante elementi di azione 



II lavoro effettivo di un'applicazione per Web server viene svolto dagli elementi di 
azione quando vengono eseguiti. Quando il dispatcher Web attiva un elemento di 
azione, questo puo reagire in due modi al messaggio di richiesta corrente: 

• Se all'elemento di azione e associato come valore della sua proprieta Producer un 
componente produttore, questo assegna automaticamente il Content del messaggio 
di risposta utilizzando il proprio metodo Content. La pagina Internet della 
Component palette contiene molti componenti produttori di contenuti utili a 
costruire una pagina HTML contenente il messaggio di risposta. 

• Dopo che il produttore ha assegnato il contenuto della risposta (se c'e un 
produttore associato), l'elemento di azione riceve un evento OnAction. Al gestore 
di evento OnAction vengono passati l'oggetto TWebRequest rappresentante il 
messaggio di richiesta HTTP e un oggetto TWebResponse per compilare le 
informazioni di risposta. 

Se il contenuto dell'elemento di azione puo essere generato da un unico produttore 
di contenuti, e piu semplice assegnarlo come proprieta Producer dell'elemento di 
azione. Tuttavia, mediante il gestore di evento OnAction si puo sempre accedere 
anche a qualsiasi produttore di contenuti. II gestore di evento OnAction consente piu 
flessibilita , in modo che sia possibile utilizzare piu produttori di contenuti, stabilire 
le proprieta dei messaggi di risposta, e cosi via. 

Per rispondere ai messaggi di richiesta sia il componente produttore di contenuti che 
il gestore di evento OnAction possono utilizzare qualsiasi oggetto e qualsiasi metodo 
di libreria. Infatti, possono accedere a database, eseguire calcoli, comporre o 
selezionare documenti HTML e cosi via. Per maggiori informazioni sulla generazione 
di contenuti di risposta utilizzando componenti produttori di contenuti, consultare la 
sezione "Generazione del contenuto dei messaggi di risposta" a pagina 33-14. 

Invio della risposta 

Un gestore di evento OnAction puo spedire la risposta al client Web utilizzando i 
metodi dell'oggetto TWebResponse. Tuttavia, se nessun elemento di azione invia la 
risposta al client, questa verra spedita dall'applicazione per Web server fino a 
quando l'ultimo elemento di azione che esaminera la richiesta non indichera che essa 
e stata portata a termine. 
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Utilizzo di piu elementi di azione 

E possibile rispondere a una richiesta usando un singolo elemento di azione, oppure 
ripartendo il lavoro tra piu elementi. Se l'elemento di azione non termina 
completamente la preparazione del messaggio di risposta, deve segnalare questo 
stato nel gestore di evento OnAction mediante l'impostazione a false del parametro 
Handled. 

Se molti elementi di azione si suddividono il compito di rispondere ai messaggi di 
richiesta, ciascuno impostando Handled a false in modo da consentire agli altri di 
continuare, assicurarsi che l'elemento di azione predefinito lasci il parametro Handled 
impostato a true. Altrimenti, al client Web non verra inviata nessuna risposta. 

Quando si ripartisce il lavoro tra piu elementi di azione, il gestore di evento OnAction 
dell'elemento di azione predefinito oppure il gestore di evento AfterDispatch del 
dispatcher devono verificare se l'incombenza e stata portata a termine e riportare il 
codice di errore appropriato in caso contrario. 

Accesso alle informazioni della richiesta client 



Quando l'applicazione per Web server riceve un messaggio di richiesta HTTP, 
l'intestazione della richiesta client viene caricata nelle proprieta di un oggetto 
TWebRequest. Nelle applicazioni NSAPI e ISAPI, il messaggio di richiesta e 
incorporato in un oggetto TISAPIRequest. Le applicazioni CGI di console utilizzano 
oggetti TCGIRequest, mentre le applicazioni Windows CGI utilizzano oggetti 
TWinCGIRequest. 

Le proprieta dell'oggetto di richiesta sono di sola lettura. Queste possono essere 
utilizzate per raccogliere tutte delle informazioni disponibile nella richiesta client. 

Proprieta contenenti informazioni dello header della richiesta 



In un oggetto di richiesta, la maggior parte delle proprieta contengono informazioni 
riguardanti la richiesta indicate nello header della richiesta HTTP. Non tutte le 
richieste forniscono il valore di ognuna di queste proprieta. Inoltre, alcune richieste 
possono comprendere campi di intestazione che non affiorano in una proprieta 
dell'oggetto di richiesta, soprattutto perche lo standard HTTP e in costante 
evoluzione. Per ottenere il valore di un campo dello header della richiesta non 
identificato come proprieta dell'oggetto richiesta, si ricorre al metodo 
GetFieldByName. 

Proprieta che identificano la destinazione 

La destinazione completa di un messaggio di richiesta e data dalla sua proprieta 
URL. Di solito, e una URL che si puo suddividere in protocollo (HTTP), Host (sistema 
server), ScriptName (applicazione server), Pathlnfo (ubicazione sull'host) e Query. 

Ogni segmento emerge nella propria proprieta. II protocollo e sempre HTTP, mentre 
Host e ScriptName identificano l'applicazione per Web server. II dispatcher utilizza la 
parte Pathlnfo quando fa corrispondere elementi di azione ai messaggi di richiesta. 
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Query e utilizzato da alcune richieste per specificare i dettagli delle informazioni 
chieste. II suo valore viene analizzato come la proprieta QueryFields. 

Proprieta che descrivono il client Web 

La richiesta include anche molte proprieta che forniscono informazioni sull'origine 
della richiesta. Queste includono tutte le informazioni disponibili, dall'indirizzo di 
posta elettronica del mittente (proprieta From) all'URI da cui ha avuto origine il 
messaggio (proprieta Referer o RemoteHost). Se la richiesta include un contenuto non 
proveniente dalla URI da cui proviene la richiesta, l'origine del contenuto e data dalla 
proprieta DerivedFrom. Si possono anche determinare l'indirizzo IP del client (la 
proprieta RemoteAddr) e il nome e la versione dell'applicazione che ha inviato la 
richiesta (la proprieta User Agent). 

Proprieta che identificano lo scopo della richiesta 

La proprieta Method e una stringa che descrive quello che il messaggio di richiesta 
chiede di fare all'applicazione server. Lo standard HTTP 1.1 definisce i seguenti 



metodi: 


Valore 


Che cosa richiede il messaggio 


OPTIONS 


Informazioni sulle opzioni di comunicazione disponibili. 


GET 


Informazioni identificate dalla proprieta URL. 


HEAD 


Informazioni di intestazione da un messaggio equivalente GET, senza il 




contenuto della risposta. 


POST 


All'applicazione server di registra i dati inclusi nella proprieta Content, come 




appropriate 


PUT 


All'applicazione server di sostituire nella risorsa indicata dalla proprieta URL i 




dati presenti nella proprieta Content. 


DELETE 


All'applicazione server di cancellare o nascondere la risorsa identificata dalla 




proprieta URL. 


TRACE 


All'applicazione server di inviare una "ricevuta di ritorno" per confermare di 




aver ricevuto la richiesta. 



La proprieta Method puo indicare qualsiasi altro metodo che il client Web richiede al 
server. 

L'applicazione per Web server non deve fornire una risposta a ogni possibile valore 
di Method. Lo standard HTTP vuole pero che esso tratti sia le richieste GET che quelle 
HEAD. 

La proprieta MethodType indica se il valore di Method e GET (mtGet), HEAD (mtHead), 
POST (mtPost), PUT (mtPut) o un'altra stringa (mtAny). II dispatcher fa 
corrispondere il valore della proprieta MethodType al MethodType di ogni elemento di 
azione. 

Proprieta che descrivono la risposta prevista 

La proprieta Accept indica i tipi di supporto mediatico che il client Web accetta come 
contenuto del messaggio di risposta. La proprieta IfModifiedSince specifica se il client 
vuole solo informazioni che sono cambiate recentemente. La proprieta Cookie include 
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informazioni di stato (di solito aggiunte precedentemente dall'applicazione) che 
possono modificare la risposta. 

Proprieta che descrivono il contenuto 

La maggior parte delle richieste sono prive di contenuto, in quanta chiedono solo 
informazioni. Tuttavia, alcune richieste, come le richieste POST, forniscono un 
contenuto che si prevede verra utilizzato dall'applicazione per Web server. II tipo di 
supporto del contenuto e fornito nella proprieta ContentType e la sua lunghezza nella 
proprieta ContentLength. Se il contenuto del messaggio e stato codificato (ad esempio, 
per la compressione dati), queste informazioni si trovano nella proprieta 
ContentEncoding. II nome e il numero di versione dell'applicazione che ha prodotto il 
contenuto e specificato dalla proprieta ContentVersion. Anche la proprieta Title puo 
fornire informazioni sul contenuto. 

II contenuto dei messaggi di richiesta HTTP 



Oltre ai campi di intestazione, alcuni messaggi di richiesta includono una porzione di 
contenuto che l'applicazione per Web server deve elaborare in qualche modo. Ad 
esempio, una richiesta POST puo includere informazioni da aggiungere a un 
database gestito dall'applicazione per Web server. 

II valore non elaborato del contenuto e dato dalla proprieta Content. Se questo puo 
essere suddiviso in campi separati da simboli (&), una versione scomposta e 
disponibile nella proprieta ContentFields. 

Creazione di messaggi di risposta HTTP 



Quando l'applicazione per Web server crea un oggetto TWebRequest in risposta a un 
messaggio di richiesta HTTP in arrivo, crea anche un oggetto corrispondente 
TWebResponse che rappresenta il messaggio di risposta che sara inviato. Nelle 
applicazioni NSAPI e ISAPI, il messaggio di risposta e incorporato in un oggetto 
TISAPIResponse. Le applicazioni CGI di console utilizzano oggetti TCGIResponse, 
mentre le applicazioni Windows CGI utilizzano oggetti TWinCGIResponse. 

Gli elementi di azione che generano la risposta a una richiesta Web client riempiono 
le proprieta dell'oggetto di risposta. In alcuni casi, e una cosa semplice, come 
restituire un codice di errore, o inoltrare la richiesta a un altro URL In altri casi, 
possono essere necessari calcoli complessi che richiedono all'elemento di azione di 
prelevare informazioni da altre sorgenti e di dare loro una forma finita. La maggior 
parte dei messaggi di richiesta richiedono una risposta, anche se se si tratta solo della 
conferma che l'azione richiesta e stata eseguita. 

Compilazione dell'intestazione della risposta 



La maggior parte delle proprieta dell'oggetto TWebResponse rappresentano le 
informazioni di intestazione del messaggio di risposta HTTP inviato al client Web. 
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Un elemento di azione imposta queste proprieta prendendole dal proprio gestore di 
evento On Action. 

Non tutti i messaggi di risposta devono specificare il valore di ciascuna proprieta 
dell'intestazione. Le proprieta da impostare dipendono dalla natura della richiesta e 
dallo stato della risposta. 

Indicazione dello stato della risposta 

Ogni messaggio di risposta deve includere un codice di stato che indica lo stato della 
risposta. II codice di stato si imposta mediante la proprieta StatusCode. Lo standard 
HTTP definisce molti codici di stato standard dal significato predefinito. Inoltre, si 
possono definire codici di stato non standard utilizzando qualsiasi valore inutilizzato 
ammissibile. 

Ogni codice di stato e un numero di tre cifre dove la cifra piu significativa indica la 
classe della risposta, come segue: 

• lxx: Informational (la richiesta e stata ricevuta ma non e stata elaborata 
completamente) . 

• 2xx: Success (la richiesta e stata ricevuta, capita e accettata). 

• 3xx: Redirection (un'ulteriore iniziativa da parte del client e necessaria per 
completare la richiesta). 

• 4xx: client Error (la richiesta non e comprensibile o non puo essere eseguita). 

• 5xx: Server Error (la richiesta era valida ma il server non ha potuto gestirla). 

A ogni codice di stato e associata una stringa che ne spiega il significato. Si tratta 
della proprieta ReasonString. Nel caso dei codici di stato predefiniti, non e necessario 
impostare la proprieta ReasonString. Se invece si definiscono codici di stato non 
standard, e bene impostare la proprieta ReasonString. 

Indicazione della necessita di azione da parte del client 

Quando il codice di stato e compreso nell'intervallo 300-399, il client deve eseguire 
un'ulteriore azione prima che l'applicazione per Web server possa portare a termine 
la sua richiesta. Se e necessario dirigere il client verso un altro URI, o indicare che per 
gestire la richiesta e stato creato un nuovo URI, si deve impostare la proprieta 
Location. Se il client deve fornire una password prima che sia possibile procedere, si 
imposta la proprieta WWW Authenticate. 

Descrizione dell'applicazione server 

Alcune delle proprieta di intestazione della risposta descrivono le possibility 
dell'applicazione per Web server .La proprieta Allow indica i metodi a cui 
l'applicazione puo rispondere. La proprieta Server da il nome e il numero di versione 
dell'applicazione utilizzata per generare la risposta. La proprieta Cookies puo ospitare 
informazioni di stato sull'utilizzo da parte del client dell'applicazione server 
contenuta nei successivi messaggi di richiesta. 
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Descrizione del contenuto 

Numerose proprieta descrivono il contenuto della risposta. ContentType indica il tipo 
di supporto mediatico della risposta e ContentVersion e il numero di versione relativo 
a quel tipo di supporto. ContentLength da la lunghezza della risposta. Se il contenuto 
e codificato (come nel caso di una compressione dati), lo si segnala tramite la 
proprieta ContentEncoding. Se il contenuto proviene da un altro URI, lo si indica nella 
proprieta DerivedFrom. Se il valore del contenuto dipende dal tempo, la proprieta 
LastModified e la proprieta Expires indicano se il valore e ancora valido. La proprieta 
Title fornisce informazioni descrittive sul contenuto. 

Impostazione del contenuto della risposta 



Per alcune richieste, la risposta al messaggio di richiesta e contenuta completamente 
nelle proprieta dell'intestazione della risposta. Comunque, nella maggior parte dei 
casi, l'elemento di azione assegna parte dei contenuti al messaggio di risposta. Tali 
contenuti possono essere informazioni statiche registrate in un file o informazioni 
prodotte dinamicamente dall'elemento di azione o dal proprio produttore di 
contenuti. 

E possibile impostare il contenuto del messaggio di risposta utilizzando la proprieta 
Content oppure la proprieta ContentStream. 

La proprieta Content e una AnsiString. Le AnsiString di C++Builder non sono 
limitate a valori del testo, e pertanto il valore della proprieta Content pud essere una 
stringa di comandi HTML, oppure contenuti grafici sotto forma di stream di bit, o 
qualsiasi altro contenuto di tipo MIME. 

Si utilizza la proprieta ContentStream se il contenuto del messaggio di risposta puo 
essere letto da un flusso. Ad esempio, se il messaggio di risposta deve inviare il 
contenuto di un file, si utilizza un oggetto TFileStream per la proprieta ContentStream. 
Come nel caso della proprieta Content, ContentStream puo fornire una stringa di 
comandi HTML o un altro tipo di contenuto MIME. Quando viene usata la proprieta 
ContentStream, non c'e bisogno di liberare esplicitamente il flusso. E' l'oggetto di 
risposta Web che lo libera automaticamente. 

Se il valore della proprieta ContentStream non e NULL, la proprieta Content viene 
ignorata. 

Invio della risposta 



Se si ha la certezza che non c'e altro lavoro da fare per rispondere a un messaggio di 
richiesta, si puo far spedire la risposta direttamente da un gestore di evento 
OnAction. L'oggetto di risposta ha due metodi per inviarla: SendResponse e 
SendRedirect. Si chiama SendResponse per mandare la risposta utilizzando il contenuto 
specificato e tutte le proprieta dell'intestazione dell'oggetto TWebResponse. Se basta 
reindirizzare il client Web a un altro URI, il metodo SendRedirect e piu efficiente. 

Se nessuno dei gestori di evento invia la risposta, l'oggetto Web application la invia 
quando il dispatcher ha finite Tuttavia, se nessun elemento di azione segnala di aver 



Utilizzo di Web Broker 33-13 



Generazione del contenuto dei messaggi di risposta 

gestito la risposta, l'applicazione chiude la connessione con il client Web senza 
inviare nessuna risposta. 

Generazione del contenuto dei messaggi di risposta 



C++Builder fornisce una serie di oggetti per assistere gli elementi di azione nella 
produzione dei contenuti dei messaggi HTTP di risposta. Si possono usare per 
generare stringhe di comandi HTML che vengono salvati in un file o inviati 
direttamente al client Web. Si possono scrivere dei generatori di contenuti facendoli 
derivare da TCustomContentProducer o da uno dei suoi discendenti. 

TCustomContentProducer fornisce un'interfaccia generica per la creazione di qualsiasi 
tipo MIME, come il contenuto di un messaggio di risposta HTTP. Tra i suoi 
discendenti vi sono produttori di pagine e produttori di tabelle: 

• I produttori di pagine analizzano i documenti HTML cercando tag particolari che 
vengono sostituiti da un codice HTML ad hoc. Vengono illustrati nella prossima 
sezione. 

• I produttori di tabelle creano comandi HTML in base alle informazioni presenti in 
un dataset. Sono descritti nel paragrafo "Utilizzo nelle risposte di informazioni di 
database" a pagina 33-18. 

Utilizzo di componenti produttori di pagine 



I produttori di pagine (TPageProducer e discendenti) prendono un modello HTML e 
lo convertono sostituendo tag speciali non visibili da HTML con codice 
personalizzato HTML. Si puo memorizzare un insieme dei modelli risposta standard 
che vengono compilati dai produttori di pagine quando bisogna generare la risposta 
a un messaggio di richiesta HTTP. Si possono concatenare piu produttori di pagine e 
costruire iterativamente un documento HTML con successivi aff inamenti dei tag 
HTML trasparenti. 

Modelli HTML 

Un modello HTML e una sequenza di comandi HTML e di tag HTML trasparenti. Un 
tag HTML trasparente ha la forma 

<#TagName Paraml=Valuel Param2=Value2 ...> 

Le parentesi angolari (< e >) definiscono l'intero campo d'azione del tag. II simbolo 
(#) segue immediatamente la parentesi angolare aperta (<) senza spazi vuoti tra l'una 
e l'altra. II simbolo # segnala al produttore di pagine che si tratta di un tag HTML 
trasparente. II nome del tag segue immediatamente il simbolo #. II nome del tag puo 
essere qualsiasi identificativo valido e individua il tipo di conversione che il tag 
rappresenta. 

Dopo il nome del tag, il tag HTML trasparente puo includere facoltativamente 
parametri che specificano i dettagli della conversione da effettuare. Ogni parametro 
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ha il formato ParamName -Value, senza spazi vuoti tra il nome del parametro, il 
simbolo (=) e il valore. I parametri sono separati da spazi vuoti. 

Le parentesi angolari (< e >) rendono il tag trasparente ai browser HTML che non 
riconoscono il costrutto #TagName. 

Benche sia possibile creare dei marcatori HTML-trasparenti personalizzati per 
rappresentare qualsiasi tipo di informazione trattato dal proprio produttore di 
pagine, esistono svariati nomi di marcatori predefiniti associati a valori del tipo dati 
TTag. Questi nomi di marcatori predefiniti corrispondono ai comandi HTML che e 
abbastanza probabile trovare nei messaggi di risposta. Questi nomi del tag 
predefiniti corrispondono a comandi HTML che facilmente variano in relazione ai 
messaggi di risposta e che sono riportati nella seguente tabella: 



Valore di 


Link 


tgLink 


Collegamento ipertestuale. 11 risultato e una sequenza HTML 
che inizia con il tag <A> e finisce con il tag </ A>. 


Image 


tglmage 


Immagine grafica. 11 risultato e il tag HTML <IMG>. 


Table 


tgTable 


Tabella HTML. 11 risultato e una sequenza HTML che inizia 
con il tag <TABLE> e finisce con il tag </TABLE>. 


ImageMap 


tglmageMap 


Immagine grafica con zone calde associate. 11 risultato e una 
sequenza HTML che inizia con il tag <MAP> e finisce con il 
tag </MAP>. 


Object 


tgObject 


Un oggetto incorporato ActiveX. 11 risultato e una sequenza 
HTML che inizia con il tag <OBJECT> e finisce con il tag </ 
OBJECTx 


Embed 


tgEmbed 


DLL di add-in conforme a Netscape -. 11 risultato e una 
sequenza HTML che inizia con il tag <EMBED> e finisce con il 
tag </EMBED>. 



Qualsiasi altro nome di marcatore viene associato a tgCustom. II produttore di pagine 
non fornisce nessuna elaborazione intrinseca dei nomi di marcatore predefiniti. II 
produttore di pagine non elabora in alcun modo i nomi di tag predefiniti, che 
servono solo per aiutare le applicazioni a organizzare il processo di conversione in 
molte delle attivita piu comuni. 

I nomi di tag predefiniti non riconoscono la differenza tra maiuscole e minuscole. 

Specif ica del modello HTML 

I produttori di pagine offrono molte possibility per specificare il modello HTML. Si 
puo dare alia proprieta HTMLFile il nome di un file contenente il modello HTML. Si 
puo impostare la proprieta HTMLDoc a un oggetto TStrings contenente il modello 
HTML. Utilizzando per specificare il modello o la proprieta HTMLFile o la proprieta 
HTMLDoc, e possibile generare i comandi convertiti HTML chiamando il metodo 
Content. 

Inoltre, e possibile chiamare il metodo ContentFromString per convertire direttamente 
un modello HTML passatogli come parametro sotto forma di una singola AnsiString. 
E possibile anche chiamare il metodo ContentFromStream per leggere il modello 
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HTML da un flusso. Cosi, ad esempio, si potrebbero memorizzare tutti i modelli 
HTML in un campo memo di un database e utilizzare il metodo ContentFromStream 
per ottenere i comandi convertiti HTML, leggendo il modello direttamente da un 
oggetto TBlobStream. 

Conversione dei tag HTML trasparenti 

Se si chiama uno dei suoi metodi Content, il produttore di pagine converte il modello 
HTML. Quando Content incontra un tag HTML trasparente, attiva l'evento 
OnHTMLTag. Per determinare il tipo di tag incontrato e sostituirlo con contenuto 
personalizzato e necessario scrivere un gestore di evento. 

Non creando il gestore di evento OnHTMLTag del produttore di pagine, i tag HTML 
trasparenti sono sostituiti da una stringa vuota. 

Utilizzo dei produttori di pagine da un elemento di azione 

In un impiego tipico, un componente produttore di pagine utilizza la proprieta 
HTMLFile per specificare un file contenente un modello HTML. II gestore di evento 
OnAction chiama il metodo Content per convertire il modello in una sequenza HTML 
definitiva: 

void fastcall WebModulel: :MyActionEventHandler(TObject *Sender, 

TWebRequest *Request, TWebResponse *Response, bool &Handled) 

{ 

PageProducerl->HTMLFile = "Greeting.html"; 
Response->Content = PageProducerl->Content ( ) ; 

} 

Greeting.html e un file che contiene questo modello HTML: 

<HTML> 

<HEADxTITLE>Our Brand New Web Site</TITLEx/HEAD> 
<B0DY> 

Hello <#UserName>! Welcome to our Web site. 

</B0DY> 
</HTML> 

II gestore di evento OnHTMLTag sostituisce nell'HTML il tag ad hoc (<#UserName>) 
durante l'esecuzione: 

void __fastcall WebModulel: :HTMLTagHandler (TObject *Sender, TTag Tag, 

const AnsiString TagString, TStrings *TagParams, AnsiString &ReplaceText ) 

{ 

if (CompareText (TagString, "UserName") == 0) 
ReplaceText = ( (TPageProducer *)Sender)->Dispatcher->Request->Content; 

} 

Se il contenuto del messaggio di richiesta fosse la stringa Mr. Ed, il valore di Response- 
content sarebbe 

<HTML> 

<HEADxTITLE>Our Brand New Web Site</TITLEx/HEAD> 
<B0DY> 

Hello Mr. Ed! Welcome to our Web site. 

</B0DY> 

</HTML> 
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Questo esempio utilizza un gestore di evento OnAction per chiamare il produttore di 
contenuti e assegnare il contenuto del messaggio di risposta. Non e necessario 
scrivere un gestore di evento OnAction se la proprieta HTMLFile del produttore di 
pagine viene assegnata in fase di progettazione. In questo caso, basta assegnare 
PageProducerl come valore della proprieta Producer dell'elemento di azione per 
ottenere l'effetto ottenuto dal gestore di evento OnAction qui sopra. 

Concatenamento di produttori di pagine 

II testo di sostituzione di un gestore di evento OnHTMLTag non deve 
necessariamente essere la sequenza HTML da utilizzare nel messaggio HTTP di 
risposta. In certi casi, si utilizzano piu produttori di pagine, nei quali l'output di uno 
e l'input del successive 

II modo piu semplice per concatenare dei produttori di pagine e quello di associare 
ogni produttore di pagine a un elemento di azione separato, dove tutti gli elementi di 
azione hanno gli stessi Pathlnfo e MethodType. II primo elemento di azione imposta il 
contenuto del messaggio di risposta Web dal suo produttore di contenuti, ma il suo 
gestore di evento OnAction si assicura che il messaggio non sia considerato gestito. 
L'elemento di azione successivo utilizza il metodo ContentFromString del suo 
produttore associato per trattare il contenuto del messaggio di risposta Web, e cosi 
via. Gli elementi di azione dopo il primo utilizzano un gestore di evento OnAction 
come il seguente: 

void __fastcall WebModulel: :Action2Action(TObject *Sender, 
TWebRequest *Request, TWebResponse *Response, bool &Handled) 

{ 

Response->Content = PageProducer2->ContentFromString(Response->Content) ; 

} 

Ad esempio, si consideri un'applicazione che restituisce pagine di calendario in 
risposta a messaggi di richiesta che specificano il mese e l'anno della pagina chiesta. 
Ogni pagina del calendario contiene un'immagine, seguita dal nome e dall'anno del 
mese fra piccole immagini del mese precedente e dei mesi prossimi, seguiti dal 
calendario vero e proprio. L'immagine che ne risulta si presenta cosi: 




La scheda generale del calendario memorizzata in un file modello. Si presenta cosi: 



<HTML> 

<Headx/HEAD> 

<B0DY> 

<#MonthlyImage> <#TitleLinex#MainBody> 

</B0DY> 

</HTML> 
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II gestore di evento OnHTMLTag del primo produttore di pagine cerca il mese e 
l'anno dal messaggio di richiesta. Utilizzando quelle informazioni e il file modello, fa 
quanto segue: 

• Sostituisce <#MonthlyImage> con <#Image Month=January Year=2000>. 

• Sostituisce <#TitleLine> con <#Calendar Month=December Year=1999 
Size=Small> January 2000 <#Calendar Month=February Year=2000 Size=Small>. 

• Sostituisce <#MainBody> con <#Calendar Month= January Year=2000 
Size=Large>. 

II gestore di evento OnHTMLTag del successivo produttore di pagine usa i contenuti 
prodotti dal primo produttore di pagine e sostituisce il marcatore <#Image 
Month =January Year=2000> con l'opportuno marcatore HTML <IMG>. Un ulteriore 
produttore di pagine risolve i tag #Calendar con tabelle appropriate HTML. 

Utilizzo nelle risposte di informazioni di database 



La risposta a un messaggio di richiesta HTTP puo comprendere anche informazioni 
tratte da un database. Alcuni produttori di contenuti specializzati alia pagina 
Internet della Component palette possono generare il codice HTML capace di 
rappresentare in una tabella HTML i record tratti da un database. 

Come approccio alternative certi componenti speciali contenuti nella pagina 
InternetExpress della Component palette consentono di realizzare Web server che 
fanno parte di un'applicazione database multi-tier. Per i dettagli "Creazione di 
applicazioni Web con InternetExpress" a pagina 29-33. 

Aggiunta di una sessione a un modulo Web 



Sia le applicazioni CGI di console che le applicazioni Win-CGI vengono lanciate in 
risposta a messaggi di richiesta HTTP. Quando in questi tipi di applicazioni si ha a 
che fare con un database, e possibile utilizzare la sessione predefinita per gestire le 
connessioni database, perche ogni messaggio di richiesta ha una propria istanza 
dell'applicazione. Ogni istanza dell'applicazione ha una propria sessione predefinita. 

Scrivendo un'applicazione ISAPI o un'applicazione NSAPI, tuttavia, ogni messaggio 
di richiesta e gestito da un thread distinto di una singola istanza di applicazione. Per 
impedire alle connessioni database di vari thread di interferire l'una con l'altra, 
bisogna assegnare a ogni thread una propria sessione. 

Ogni messaggio di richiesta in un'applicazione ISAPI o NSAPI produce un nuovo 
thread. II modulo Web del thread in questi one e generato dinamicamente in fase di 
esecuzione. Si aggiunge un oggetto TSession al modulo Web per gestire le 
connessioni database del thread contenente il modulo Web. 

In fase di esecuzione, per ciascun thread viene generata un'istanza distinta del 
modulo Web. Ciascun modulo contiene l'oggetto sessione. Ciascuna sessione deve 
avere il proprio nome, in modo che i thread che gestiscono i diversi messaggi di 
richiesta non interferiscano con le connessioni dei database. Per fare in modo che gli 
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oggetti sessione in ogni modulo generino dinamicamente nomi univoci, si imposta la 
proprieta AutoSessionName dell'oggetto sessione. Ogni oggetto sessione generera 
dinamicamente un proprio nome univoco e impostera la proprieta SessionName di 
tutti i dataset nel modulo, in modo che facciano riferimento a quel nome univoco. 
Questo consente a ogni singolo thread di richiesta di interagire con il database senza 
interferire con gli altri messaggi di richiesta. Per ulteriori informazioni sule sessioni, 
consultare "Gestione delle sessioni di database" a pagina 24-17. 

Rappresentazione di informazioni di database in HTML 



I componenti produttori di contenuti specializzati della pagina Internet della 
Component palette dispongono di comandi HTML basati sui record di un dataset. Ci 
sono due tipi di produttori di contenuti associati ai dati: 

• II produttore di pagine di dataset, che formatta i campi di un dataset nel testo di 
un documento HTML. 

• I produttori di tabelle, che formattano i record di un dataset come una tabella 
HTML. 

Utilizzo dei produttori di pagine di dataset 

I produttori di pagine di dataset funzionano come gli altri componenti produttori di 
pagine: convertono un modello comprendente tag HTML trasparenti in una 
rappresentazione finale HTML. Tuttavia, sono anche in grado di convertire i tag che 
hanno un tagname corrispondente al nome di un campo di un dataset nel valore 
corrente del campo. Per ulteriori informazioni sull'utilizzo di produttori di pagine in 
generale, consultare "Utilizzo di componenti produttori di pagine" a pagina 33-14. 

Per utilizzare un produttore di pagine di dataset, aggiungere un componente 
TDataSetPageProducer al modulo Web e impostarne la proprieta DataSet al dataset i 
cui campi dovrebbero essere visualizzati nei contenuti HTML. Si crea un modello 
HTML che descrive l'output del produttore di pagine di dataset. Per ciascun valore 
di campo che si desidera visualizzare, si mette nel modello HTML un tag in formato 

<#FieldName> 

dove FieldName specifica il nome del campo nel dataset di cui si vuole visualizzare il 
valore. 

Quando l'applicazione chiama il metodo Content, ContentFromString o 
ContentFromStream, il produttore di pagine di dataset sostituisce i valori del campo 
correnti con i tag che rappresentano campi. 

Utilizzo di produttori di tabelle 

La pagina Internet della Component palette contiene due componenti che creano 
tabelle HTML per rappresentare i record di un dataset: 

• Produttori di tabelle di dataset, che formattano i campi di un dataset nel testo di 
un documento HTML. 
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• Produttori di tabelle di query, che eseguono una query dopo avere impostato i 
parametri f orniti dal messaggio di richiesta e che formattano come tabella HTML 
il dataset risultante. 

Utilizzando l'uno o l'altro dei due produttori di tabelle, e possibile adattare l'aspetto 
della tabella HTML risultante specificando le proprieta per il colore, il margine, lo 
spessore dei separatori e cosi via. Per impostare in fase di progetto le proprieta di un 
produttore di tabelle, fare doppio clic sul componente produttore di tabelle in modo 
da visualizzare la finestra di dialogo Response Editor. 

Specifica degli attributi di tabella 

Per rappresentare visivamente la tabella HTML che visualizza i record dal dataset i 
produttori di tabelle utilizzano l'oggetto THTMLT able Attributes. L'oggetto 
THTML1 ^able Attributes dispone di proprieta per fissare la larghezza e la spaziatura 
della tabella nel documento HTML per il colore di sfondo, lo spessore del bordo, il 
suo riempitivo e la sua spaziatura di cella. Queste proprieta sono trasformate in 
opzioni nel tag HTML <TABLE> creato dal produttore di tabelle. 

In fase di progettazione, queste proprieta si specificano utilizzando V Object Inspector. 
Selezionare l'oggetto produttore di tabella r\e\Y Object Inspector ed espandere la 
proprieta Table Attributes per accedere alle proprieta di visualizzazione dell'oggetto 
THTMLTableAttributes. 

E possibile anche specif icare queste proprieta da programma in fase di esecuzione. 

Specifica degli attributi di riga 

Come nel caso degli attributi di tabella, si possono specificare l'allineamento e il 
colore di sfondo delle celle nelle righe della tabella che visualizzano dati. La 
proprieta RowAttributes e un oggetto THTMLTableRow Attributes. 

In fase di progettazione, queste proprieta si specificano utilizzando 1 'Object Inspector 
ed estendendo la sua proprieta RowAttributes. 

Impostando la proprieta MaxRows, si puo anche regolare il numero di righe 
visualizzate di una tabella HTML. 

Specifica delle colonne 

Se in fase di progettazione si conosce il dataset della tabella, e possibile utilizzare il 
Columns editor per personalizzare i collegamenti e gli attributi di visualizzazione di 
campo delle colonne. Selezionare il componente produttore di tabelle e fare clic con il 
pulsante destro. Nel menu di scelta rapida, scegliere il Columns editor. Si possono 
cosi aggiungere, cancellare o riordinare le colonne nella tabella. E possibile impostare 
i collegamenti di campo e visualizzare le proprieta delle singole colonne nell'Object 
Inspector, dopo averle selezionate nel Columns editor. 

Se il nome del dataset viene ottenuto tramite il messaggio di richiesta HTTP, e 
impossibile in fase di progettazione collegare i campi nel Columns editor. In fase di 
esecuzione, si possono pero personalizzare le colonne mediante un programma 
configurando gli oggetti appropriati THTMLT ableColumn e utilizzando i metodi della 
proprieta Columns per inserirli nella tabella. Se non si configura la proprieta Columns, 
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il produttore di tabella crea un set predefinito di colonne corrispondenti ai campi del 
dataset senza pero impostare particolari caratteristiche di visualizzazione. 

Inserimento di tabelle nei documenti HTML 

Utilizzando le proprieta Header e Footer di un produttore di tabelle, si pud 
incorporare la tabella HTML che rappresenta il dataset in un documento piu grande. 
Header serve per specificare tutto cio che viene prima della tabella e Footer per 
specificare tutto cio che viene dopo la tabella. 

Per creare i valori delle proprieta Header e Footer conviene utilizzare un altro 
produttore di contenuti (come un produttore di pagine). 

Se la tabella viene inclusa in un documento piu grande, conviene aggiungere 
un'intestazione. Alio scopo, si utilizzano le proprieta Caption e Caption Alignment. 

Impostazione di un produttore di tabelle di dataset 

TDataSetTableProducer e un produttore di tabelle che crea una tabella HTML per un 
dataset. Per specificare il dataset contenente i record da visualizzare, si imposta la 
proprieta DataSet di TDataSetTableProducer. Non si imposta la proprieta DataSource, 
come si farebbe in un'applicazione database convenzionale con la maggior parte 
degli oggetti data-aware. Questo avviene perche TDataSetTableProducer genera il 
proprio datasource internamente. 

E possibile impostare il valore di DataSet in progettazione se l'applicazione Web 
visualizza sempre record dallo stesso dataset. E necessario impostare la proprieta 
DataSet in esecuzione se si basa il dataset sulle informazioni nel messaggio di 
richiesta HTTP. 

Impostazione di un produttore di tabelle di query 

E possibile produrre una tabella HTML per visualizzare i risultati di una query, dove 
i parametri della query provengono dal messaggio di richiesta HTTP. Specificare 
l'oggetto TQuery che utilizza quei parametri come la proprieta Query di un 
componente TQueryTableProducer. 

Se il messaggio di richiesta e una richiesta GET, i parametri della query vengono dai 
campi Query dell'URL che e stata data come destinazione del messaggio di richiesta 
HTTP. Se il messaggio di richiesta e una richiesta POST, i parametri della query 
vengono dal contenuto del messaggio di richiesta. 

Quando si chiama il metodo Content di TQueryTableProducer , la query viene eseguita, 
utilizzando i parametri che trova nell'oggetto di richiesta. Quindi viene formattata 
una tabella HTML per visualizzare i record nel dataset risultante. 

Come con qualsiasi produttore di tabella, e possibile personalizzare le proprieta dello 
schermo o i collegamenti di colonna della tabella HTML o incorporare la tabella in un 
documento HTML piu grande. 



Utilizzo di Web Broker 33-21 



Utilizzo nelle risposte di informazioni d i database 



33-22 Guida alia programmazione 



Capitolo 




Creazione di applicazioni Web 
Server con WebSnap 

WebSnap potenzia Web Broker con componenti aggiuntivi, wizard e viste — 
rendendo piu semplice la costruzione di applicazioni per Web server che 
distribuiscono pagine web data-driven complesse. II supporto di WebSnap per piu 
moduli e per lo scripting lato server server semplifica lo sviluppo e la manutenzione 
sia ai team di sviluppo in C++Builder sia ai Web designer. 

WebSnap consente agli esperti di progettazione HTML all'interno del team di 
apportare un maggior contributo alia sviluppo e alia manutenzione dei server Web. II 
prodotto finale del processo di sviluppo WebSnap include una serie di modelli di 
pagine HTML automatizzabili con script. Queste pagine possono essere modofcate 
utilizzando un editor HTML che supporti marcatori di script incorporati, come 
Microsoft FrontPage o anche un semplice editor di testi. Se occorre, le modifiche 
possono essere fatte ai modelli, anche dopo la distribuzione dell'applicazione. Non 
c'e alcuna necessita di modificare il codice sorgente del progetto, il che fa risparmiare 
prezioso tempo di sviluppo. Inoltre, il supporto per piu moduli di WebSnap puo 
essere utilizzato per suddividere l'applicazione in parti piu piccole durante la fase di 
codifica del progetto. Gli sviluppatori in C++Builder possono lavorare in modo piu 
indipendente. 

I componenti dispatcher gestiscono automaticamente richieste di contenuti di 
pagina, sottomissioni di schede HTML, e richieste di immagini dinamiche. I 
componenti WebSnap, detti adapter, mettono a disposizione la capacita di definire 
un'interfaccia automatizzabile tramite script per le regole di gestione 
dell'applicazione. Ad esempio, l'oggetto TDataSet Adapter viene utilizzato per rendere 
i componenti dataset automatizzabili tramite script. E possibile utilizzare 
componenti produttore di WebSnap per costruire velocemente moduli e tabelle data- 
driven complesse oppure per utilizzare XSL per generare una pagina. E possibile 
utilizzare il componente session per tenere traccia degli utenti finali. E possibile 
utilizzare il componente user list per fornire l'accesso a nomi utente, password e 
diritti di accesso. 
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Web application wizard permette di costruire velocemente un'applicazione che sara 
personalizzata con i componenti necessari. Web page module wizard permette di 
creare un modulo che definisce una nuova pagina nell'applicazione. Oppure 
utilizzare Web data module wizard per creare un contenitore per i componenti che 
vengono condivisi da tutta l'applicazione web. 

Le viste modulo di pagina visualizzano il risultato degli script lato server senza 
eseguire l'applicazione. E possibile visualizzare l'HTML generato in un browser 
incorporate utilizzando la pagina Preview o sotto forma di testo utilizzando la 
pagina HTML Result. La pagina HTML Script visualizza la pagina con lo script lato 
server, utilizzata per generare l'HTML per la pagina. 

Le seguenti sezioni di questo capitolo spiegano come si utilizzano i componenti 
WebSnap per creare un'applicazione per Web server. 

Componenti fondamentali di WebSnap 



Prima di potere costruire applicazioni per Web server utilizzando WebSnap, e 
necessario capire prima i componenti fondamentali utilizzati nello sviluppo 
WebSnap. Essi rientrano in tre categorie: 

• Moduli Web, che contengono i componenti che preparano l'applicazione e 
definiscono pagine 

• Adattatori, che forniscono un'interfaccia fra pagine HTML e l'applicazione per 
Web server stessa 

• Produttori di pagina, che contengono le routine che creano le pagine HTML da 
servire all'utente finale 

Le seguenti sezioni esaminano ogni tipo di componente piu in dettaglio. 

Moduli Web 



I moduli Web sono il componente di base delle applicazioni WebSnap. Ogni 
applicazione server WebSnap deve avere almeno un modulo Web. Se necessario, e 
possibile aggiungerne altri. Esistono quattro tipi di moduli Web: 

• Moduli pagina Web application (oggetti TWebAppPageModuIe) 

• Moduli dati Web application (oggetti TWebAppDataModuIe) 

• Moduli pagina Web (oggetti TWebPageModule) 

• Moduli dati Web (oggetti TWebDataModule) 

I moduli pagina web e i moduli pagina Web application forniscono i contenuti per le 
pagine web. I moduli dati Web e i moduli dati Web application agiscono come 
contenitori per i componenti condivisi all'interno dell'applicazione; nelle 
applicazioni WebSnap svolgono la stessa funzione svolta dai comuni moduli dati 
nelle normali applicazioni in C++ Builder. Nell'applicazione server e possibile 
includere un qualsiasi numero di moduli pagina Web o moduli dati. Ci si potrebbe 
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chiedere di quanti moduli ha bisogno l'applicazione Web. Ogni applicazione 
WebSnap ha bisogno di un modulo (e solo uno) Web application di qualche tipo. 
Oltre a quello, e possibile aggiungere tutti i moduli pagina Web o dati che sono 
necessari. 

Nel caso dei moduli pagina Web, una buona regola empirica e quella di avere un 
modulo per ogni stile di pagina. Se si prevede di implementare una pagina che puo 
utilizzare il formato di una pagina esistente, e possibile che non sia necessario un 
nuovo modulo pagina Web. Le modifiche a un modulo pagina esistente possono 
essere sufficienti. Se la pagina e molto diversa dai moduli esistenti, probabilmente si 
vorra creare un nuovo modulo. Ad esempio, si supponga che si stia provando a 
costruire un server per gestire online le vendite per catalogo. Le pagine che 
descrivono i prodotti disponibili potrebbero condividere tutte lo stesso modulo 
pagina Web, poiche le pagine possono contenere tutte gli stessi tipi di informazioni 
di base utilizzando la stessa disposizione. Un modulo d'ordine, tuttavia, 
probabilmente richiedera un modulo pagina Web differente, poiche il formato e la 
runzione di un modulo d'ordine sono diversi rispetto a quelli di una pagina per la 
descrizione di un prodotto. 

Le regole sono diverse nel caso dei moduli dati Web. I componenti che possono 
essere condivisi da molti moduli Web dovrebbero essere messi in un unico modulo 
dati Web in modo da semplificare l'accesso condiviso. Sara opportuno anche mettere 
i componenti che possono essere utilizzati da molte applicazioni web nel rispettivo 
modulo dati Web. In questo modo e possibile condividere facilmente quegli elementi 
tra le applicazioni. Naturalmente, se nessuna di queste considerazioni e applicabile al 
proprio caso, si potrebbe anche decidere di non utilizzare affatto i moduli dati Web. II 
loro utilizzo e analogo a quello dei normali moduli dati, e deve essere supportato del 
proprio giudizio e dalla propria esperienza. 

Tipi di modulo Web application 

I moduli Web application offrono un controllo centralizzato per le regole di gestione 
e per i componenti non visuali nell'applicazione web. I due tipi di moduli Web 
application sono riportati nella tabella seguente. 

Tabella 34.1 Tipi di modulo Web application 
Tipo di modulo 

Web application Descrizione 

Pagina Crea una pagina di contenuti. II modulo pagina contiene un 

produttore di pagine che e responsabile della generazione del 
contenuto di una pagina. II produttore di pagine visualizza la pagina 
ad esso associata quando il pathinfo della richiesta HTTP corrisponde 
al nome della pagina. Se pathinfo e vuoto, la pagina puo agire come 
pagina predefinita. 

Dati Utilizzato come un contenitore per componenti condivisi da altri 

moduli, come i componenti database utilizzati da piu moduli pagina 
web. 



I moduli Web application agiscono come contenitori per i componenti che eseguono 
funzioni per l'applicazione in generale — come la distribuzione delle richieste, la 
gestione delle sessioni e la manutenzione delle liste di utenti. Se si ha gia una certa 
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familiarita con l'architettura Web Broker, e possibile pensare ai moduli Web 
application come se fossero simili a oggetti TWeb Application. I moduli Web 
application contengono anche le funzionalita di un normale modulo Web, sia esso 
pagina o dati, a seconda del tipo di modulo Web application. II progetto puo 
contenere solo un modulo Web application. In ogni caso non sara mai necessario piu 
di un modulo; e possibile aggiungere al server i normali moduli Web per fornire una 
qualsiasi funzione supplementare desiderata. 

Utilizzare il modulo Web aplication per contenere le funzioni basilari 
dell'applicazione server. Se il server gestira una home page di qualche sorta, si 
potrebbe utilizzare per il modulo Web application un TWebAppPageModule invece di 
un TWebAppDataModule, in modo da non dover creare un modulo pagina Web 
aggiuntivo per quella pagina. 

Moduli pagina Web 

Ad ogni modulo pagina Web e associato un produttore di pagine. Non appena riceve 
una richiesta, il dispatcher delle pagine analizza la richiesta e chiama il modulo 
pagina appropriato per elaborare la richiesta e restituire il contenuto della pagina. 

Analogamente ai moduli dati Web, i moduli pagina Web sono contenitori per 
componenti. Tuttavia, un modulo pagina Web e molto di piu di un mero contenitore. 
Un modulo pagina Web e utilizzato specif icatamente per produrre una pagina web. 

Tutti i moduli pagina Web hanno una vista editor, chiamata Preview, che permette di 
vedere in anteprima la pagina man mano che la si costruisce. E possibile sfruttare 
completamente l'ambiente visuale per lo sviluppo di applicazioni offerto da 
C++Builder. 

Componente produttore di pagine 

I moduli pagina Web hanno una proprieta che identifica il componente produttore di 
pagine responsabile della generazione dei contenuti della pagina. (Pe rmaggiori 
informazioni sui produttori di pagina, vedere "Produttori di pagina" on page 34-7.) 
WebSnap page module wizard aggiunge automaticamente un produttore quando si 
crea un modulo pagina Web. E possibile modificare in seguito il componente 
produttore di pagine prelevando un produttore diverso dalla tavolozza WebSnap. Se 
il modulo pagina ha un file di modello, assicurarsi tuttavia che il contenuto di questo 
file sia compatibile con il nuovo componente produttore. 

Nome della pagina 

I moduli pagina Web hanno un nome di pagina che puo essere utilizzato per 
referenziare la pagina in una richiesta HTTP o all'interno della logica 
dell'applicazione. Una factory nella unit del modulo pagina Web specifica il nome 
della pagina per il modulo pagina Web. 

Modello del produttore 

La maggior parte dei produttori di pagine utilizzano un modello. Di solito i modelli 
HTML contengono del codice HTML statico frammisto a marcatori trasparenti o a 
script lato server. Quando i produttori di pagina creano il loro contenuto, essi 
sostituiscono i marcatori trasparenti con i valori appropriati ed eseguono lo script 
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lato server per produrre l'HTML che viene visualizzato da un browser client. 
(XSLPageProducer fa eccezione. Utilizza dei modelli XSL, che contengono XSL 
invece che HTML. I modelli XSL non supportano marcatori trasparenti o script lato 
server.) 

Ai moduli pagina Web potrebbe essere associato un file di modello, gestito come 
parte della unit. Un file di modello gestito viene visualizzato nel Project Manager e 
ha gli stessi nome file e ubicazione di base del file di servizio della unit. Se il modulo 
pagina Web non ha un file di modello associato, le proprieta del componente 
produttore di pagine specificano il modello. 

Moduli dati Web 

Come i moduli dati standard, i moduli dati Web sono un contenitore per i 
componenti prelevati dalla tavolozza. I moduli dati forniscono una superficie di 
progettazione per aggiungere, rimuovere e selezionare i componenti. II modulo dati 
Web e diverso rispetto a un modulo dati standard per la struttura della unit e delle 
interfacce che il modulo dati Web implementa. 

Utilizzare il modulo dati Web come un contenitore per componenti che sono 
condivisi in tutta l'applicazione. Ad esempio, e possibile mettere un componente 
dataset in un modulo dati e accedere al dataset da: 

• un modulo pagina che visualizza una griglia, e 

• un modulo pagina che visualizza una scheda di immissione. 

E possibile anche utilizzare i moduli dati Web per contenere set di componenti 
utilizzabili da varie applicazioni per Web server. 

Struttura di una unit di un modulo dati Web 

I moduli dati standard hanno una variabile detta variabile di scheda, utilizzata per 
accedere all'oggetto modulo dati. I moduli dati Web sostituiscono la variabile con 
una funzione, che e definita nella unit di un modulo dati Web e ha lo stesso nome del 
modulo dati Web. Lo scopo della funzione e identico a quello della variabile che 
sostituisce. Le applicazioni WebSnap possono essere multithread e possono avere 
piu istanze di un particolare modulo per soddisfare piu richieste 
contemporaneamente. Quindi, si utilizza la funzione per restituire l'istanza corretta. 

La unit del modulo dati Web registra anche una factory per specificare in che modo il 
modulo dovrebbe essere gestito dall'applicazione WebSnap. Ad esempio, dei flag 
indicano se memorizzare nella cache il modulo e riutilizzarlo per altre richieste o 
distruggere il modulo una volta che e stata soddisfatta una richiesta. 

Adattatori 



Gli adattatori definiscono un'interfaccia di script per l'applicazione server. Essi 
permettono di inserire linguaggi di scripting all'interno della pagina e di reperire 
informazioni effettuando chiamate dal codice dello script agli adattatori. Ad 
esempio, e possibile utilizzare un adapter per definire i campi di dati da visualizzare 
in una pagina HTML. Una pagina HTML con script puo quindi contenere dei 
contenuti HTML e istruzioni script che acquisiscono i valori di quei campi dati. II 
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comportamento e simile a quello dei marcatori trasparenti utilizzati nelle 
applicazioni Web Broker. Gli adattatori supportano anche le azioni che eseguono 
comandi. Ad esempio, il fare clic su tin collegamento ipertestuale o il confermare una 
pagina HTML puo innescare azioni dell'adapter. 

Gli adattatori semplificano la creazione di pagine HTML in modo dinamico. 
Utilizzando adattatori nell'applicazione, e possibile includere script orientati agli 
oggetti capaci di supportare una logica condizionale e i clicli. Senza adattatori e 
scripting lato server, e necessario scrivere nei gestori di evento C++molto piu codice 
per la logica di generazione dell'HTML. L'utilizzo di adattatori puo ridurre 
notevolmente i tempo di sviluppo. 

Per maggiori dettagli sullo scripting, vedere pagina 34-33 e "Indirizzamento di 
richieste e risposte" a pagina 34-36. 

Per creare i contenuti della pagina e possibile utilizzare quattro tipi di componenti 
adapter: campi, azioni, errori e record. 

Campi 

I campi sono componenti che il produttore di pagine utilizza per ottenere i dati 
dall'applicazione e visualizzare il contenuto in una pagina web. I campi possono 
essere utilizzati anche per acquisire un'immagine. In questo caso, il campo restituisce 
l'indirizzo dell'immagine scritta sulla pagina web. Quando una pagina visualizza il 
proprio contenuto, viene inviata una richiesta all'applicazione per Web server, la 
quale richiama il dispatcher dell'adapter per ottenere l'immagine effettiva dal 
componente campo. 

Azioni 

Le azioni sono componenti che eseguono comandi per conto dell'adapter. Quando 
un produttore di pagine genera la propria pagina, il linguaggio di scripting chiama i 
componenti azione dell'adapter per restituire il nome dell'azione insieme agli 
eventuali parametri necessari per eseguire il comando. Ad esempio, si immagini di 
fare clic su un pulsante in una pagina HTML per cancellare una riga da una tabella. 
L'operazione restituisce, nella richiesta HTTP, il nome dell'azione associata al 
pulsante e un parametro che indica il numero di riga. II dispatcher dell'adapter 
individua il componente azione chiamato e passa all'azione il numero di riga sotto 
forma di parametro. 

Errori 

Gli adattatori mantengono un elenco degli errori che si verificano durante 
l'esecuzione di un' azione. I produttori di pagina possono accedere a questo elenco di 
errori e visualizzarli nella pagina web che l'applicazione restituisce all'utente finale. 

Record 

Alcuni componenti adapter, come TDataSet Adapter, rappresentano piu record. 
L'adapter fornisce un'interfaccia di scripting che consente l'iterazione fra i record. 
Alcuni adattatori supportano la paginazione e iterare solo attraverso i record alia 
pagina cor rente. 
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Produttori di pagina 



I produttori di pagina sono utilizzati per generare i contenuti per conto di un modulo 
pagina Web. I produttori di pagina forniscono le seguenti funzionalita: 

• Generano un contenuto HTML. 

• Possono referenziare un file esterno utilizzando la proprieta HTMLFile, oppure la 
stringa interna utilizzando la proprieta HTMLDoc. 

• Quando i produttori sono utilizzati con un modulo pagina Web, il modello pud 
essere un file associato a una unit. 

• I produttori generano dinamicamente il codice HTML che pud essere inserito nel 
modello utilizzando i marcatori trasparenti o lo scripting attivo. I marcatori 
trasparenti possono essere utilizzati nello stesso modo delle applicazioni 

Web Broker. Per maggiori informazioni sull'utilizzo dei marcatori trasparenti, 
vedere "Conversione dei tag HTML trasparenti" a pagina 33-16. II supporto per 
l'Active scripting permette di incorporare n ela pagina HTML JScript o VBScript. 

II metodo standard WebSnap per l'utilizzo dei produttori di pagina e il seguente. 
Quando si crea un modulo pagina Web, e necessario scegliere nel Web page module 
wizard un tipo di produttore di pagine. Vi sono molte possibility, ma la maggior 
parte degli sviluppatori WebSnap crea il prototipo delle proprie pagine utilizzando 
un adapter produttore di pagine, TAdapterPageProducer. L'adapter produttore di 
pagine permette di creare un prototipo di pagina web utilizzando un processo 
analogo al modello a componenti standard. All'adapter produttore di pagine si 
aggiunge un tipo di scheda, una scheda di adapter. Poiche sono necessari, e possibile 
aggiungere alia scheda adapter componenti adapter (come griglie adapter). 
Utilizzando adattatori produttori di pagine, e possibile creare pagine web usando 
una tecnica simile a quella standard utilizzata da C++Builder per la costruzione delle 
interfacce utente. 

Vi sono alcuni casi in cui e piu opportuno passare da un adapter produttore di 
pagine a un normale produttore di pagine. Ad esempio, uno dei compiti di un 
adapter produttore di pagine e quello di generare dinamicamente in fase di 
esecuzione script in un modello di pagina. Si potrebbe decidere che uno script statico 
potrebbe ottimizzare il server. Inoltre, gli utenti esperti con il linguaggio di scripting 
potrebbero volere apportare modifiche direttamente nello script. In questo caso, si 
deve utilizzare un normale produttore di pagina per evitare conflitti tra script 
dinamico e statico. Per apprendere come passare a un normale produttore di pagine, 
vedere "Progettazione HTML evoluta" on page 34-25 

E possibile anche utilizzare i produttori di pagina nello stesso modo in cui li si 
utilizzerebbe nelle applicazioni Web Broker, associando il produttore a un elemento 
di azione Web dispatcher. I vantaggi derivanti dall'utilizzo del modulo pagina Web 
sono 

• la capacita di vedere in anteprima il layout della pagina senza dover eseguire 
l'applicazione, e 

• la capacita di associare al modulo un nome di pagina, in modo che il dispatcher 
delle pagine possa chiamare automaticamente il produttore di pagine. 
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Creazione di applicazioni per Web server con WebSnap 



Se si guarda il codice sorgente per WebSnap, si scoprira che WebSnap comprende 
centinaia di oggetti. Infatti, WebSnap e cosi ricco di oggetti e funzioni che si potrebbe 
spendere molto tempo a studiarne in dettaglio l'architettura prima di capirlo 
completamente. Per fortuna, non e assolutamente necessario capire l'intero sistema 
WebSnap prima di cominciare a sviluppare l'applicazione server. 

In questa sezione si apprenderanno molte cose sul funzionamento di WebSnap 
creando una nuova applicazione per Web server. 

Per creare una nuova applicazione per Web server utilizzando l'architettura 
WebSnap: 

1 Scegliere il comando File I New I Other. 

2 Nella finestra di dialogo New Items, selezionare la pagina WebSnap e scegliere 
WebSnap Application. 

Viene visualizzata una finestra di dialogo (come mostrato nella Figure 34.1). 

3 Specificare il tipo server corretto. 

4 Utilizzare i componenti pulsante per specificare i componenti di modulo 
dell'applicazione. 

5 Utilizzare il pulsante Page Options per selezionare le opzioni di modulo 
dell'applicazione. 
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Figura 34.1 Finestra di dialogo New WebSnap application 



New WebSnap Applicat 



Server Type 

I II hi L i L I i 

CGI Stand-alone enecutable 
C Win-CGI Stand .alone executable 
C Apache Shared Module [DLL] 
C Web App Debugger executable 

CoClass Name: 



Application Module Component? 
ft" Page Module 
r Data Module 



■Application Module Options 



Page Name: |PageProducerPage2 



Caching: | Cache Instance 



Page Options... 



Selezione di un tipo server 



Selezionare uno dei seguenti tipi di applicazione per Web server, a seconda del tipo 
di server Web dell'applicazione. 

Tabella 34.2 Tipi di applicazione per Web server 



Tipo server 

ISAPI e NSAPI 

Apache 

Indipendente CGI 

Indipendente Win-CGI 

Eseguibile App Debugger 
Web 



Descrizione 

Configura il progetto come una DLL con i metodi esportati attesi 
dal server Web. 

Configura il progetto come una DLL con i metodi esportati attesi 
dal server Web Apache. 

Configura il progetto come un'applicazione per console, 
conforme alio standard Common Gateway Interface (CGI. 

Configura il progetto come un'applicazione Windows CGI, una 
variante del CGI standard adattato per Windows. 

Crea un ambiente per sviluppare e provare applicazioni per 
Web server. Questo tipo di applicazione non e destinato alia 
distribuzione. 



Specifica dei componenti del modulo applicazione 



I componenti application forniscono le funzionalita dell'applicazione web. Ad 
esempio, l'inserimento di un componente adapter dispatcher gestisce 
automaticamente l'invio di schede HTML e la restituzione di immagini generate 
dinamicamente. L'inserimento di un dispatcher di pagine visualizza 
automaticamente il contenuto di una pagina quando il pathinfo della richiesta HTTP 
contiene il nome della pagina. 

Se sulla finestra di dialogo New WebSnap application (vedere la Figure 34.1) si 
seleziona il pulsante Components viene visualizzata un'altra finestra di dialogo che 
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permette di selezionare uno o piu dei componenti modulo Web application. La 
finestra di dialogo, detta finestra di dialogo Web App Components, e visualizzata 
nella Figure 34.2. 

Figura 34.2 Finestra di dialogo Web App Component 



Web App Components 



fi? Application Adapter 

f End User Adapter 

|^ Page Dispatcher 

1^ Adapter DisBalctiBi 

r Dispatch Actions 

J~~ Locate File Service 

I - Sessions Service 

J - User List Service 



T A p p I icati o nAdap t e i 



TAdaprerDispatchet 



T WebD ispatcher 



TLocateFileService 
TSessionsService 



TWebUseiList 



nj Cancel j Help 



La seguente tabella contiene una breve spiegazione dei componenti disponibili: 

Tabella 34.3 Componenti Web application 
Tipo di componente Descrizione 

Application Adapter Contiene informazioni sull'applicazione, come il titolo. II tipo 

predefinito e T 'Application Adapter. 

End User Adapter Contiene informazioni sull'utente, come il loro nome, i diritti di 

accesso e se essi sono connessi o meno. II tipo predefinito e 
TEndUser Adapter. Si puo anche selezionare 
TEndUserSessianAdapter. 

Esamina il pathinfo della richiesta HTTP e chiama il modulo 
pagina appropriato per restituire il contenuto di una pagina. II tipo 
predefinito e TPageDispatcher. 

Gestisce automaticamente l'inoltro di schede HTML e le richieste 
di immagini dinamiche chiamando un adapter action e i 
componenti campo. II tipo predefinito e TAdapterDispatcher. 

Permette di definire una raccolta di elementi di azione per gestire 
richieste in base al pathinfo e al tipo di metodo. Gli elementi di 
azione chiamano eventi definiti daU'utente o richiedono il 
contenuto di componenti page producer. II tipo predefinito e 
TWebDispatcher. 

Fornisce il controllo sul caricamento dei file di modello e dei file di 
inclusione degli script mentra la Web application e in esecuzione. 
II tipo predefinito e TLocateFileService. 



Page Dispatcher 
Adapter Dispatcher 
Dispatch Actions 

Locate File Service 
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Tabella 34.3 Componenti Web application 



Tipo di componente 


Descrizione 


Sessions Service 
User List Service 


Registra le informazioni sugli utenti necessarie per un breve 
periodo di tempo. Ad esempio, e possibile utilizzare le sessioni per 
tenere traccia di utenti collegati e disconnettere automaticamente 
un utente dopo un periodo di inattivita. 11 tipo predefinito e 

TSessionsService. 

Tiene traccia degli utenti autorizzati, delle loro password e dei loro 
diritti di accesso. 11 tipo predefinito e TWebllserList. 



Per ognuno dei precedenti componenti, i tipi di componenti elencati sono i tipi 
predefiniti forniti con C++Builder. Gli utenti possono creare i propri tipi di 
componenti o utilizzare tipi di componenti forniti da terze parti. 



Selezione delle opzioni del modulo Web application 



Se il tipo di modulo di applicazione selezionato e un modulo di pagina, e possibile 
associare alia pagina un nome immettendo un nome nel campo Page Name nella 
finestra di dialogo New WebSnap Application. In esecuzione, l'istanza di questo 
modulo puo essere conservata in cache o rimossa dalla memoria una volta che la 
richiesta e stata sodisfatta. Selezionare dal campo Caching una delle due opzioni. E 
possibile selezionare altre opzioni del modulo pagina scegliendo il pulsante Page 
Options. Viene visualizzata la finestra di dialogo Application Module Page Options 
che presenta le seguenti categorie: 

• Producer: II tipo di produttore per la pagina puo essere impostato ad 
AdapterPageProducer, DataSetPageProducer, InetXPageProducer, PageProducer o 
XSLPageProducer. Se il produttore di pagine selezionato supporta lo scripting, 
utilizzare l'elenco a discesa Script Engine per selezionare il linguaggio utilizzato 
per scrivere la pagina. 

AdapterPageProducer supporta solo JScript. 

• HTML: Se il produttore selezionato utilizza un modello HTML questo gruppo sara 
visibile. 

• XSL: Se il produttore selezionato utilizza un modello XSL, come 
TXSLPageProducer, questo gruppo sara visibile. 

• New File: Selezionare New File se si vuole che un file di modello sia creato e 
gestito come parte della unit. Un file di modello gestito viene visualizzato nel 
Project Manager e ha lo stesso nome di file e ubicazione del file sorgente della unit. 
Deselezionare New File se si vogliono utilizzare le proprieta del componente 
producer (di solito la proprieta HTMLDoc o HTMLFile). 

• Template: Se New File e selezionato, scegliere il contenuto predefinito per il file di 
modello dalla caslla a discesa Template. II modello standard visualizza il titolo 
dell'applicazione, il titolo della pagina e i collegamenti ipertestuali alle pagine 
pubblicate. II modello vuoto crea una pagina vuota. 

• Page: Immettere un nome di pagina e un titolo per il modulo pagina. II nome della 
pagina viene utilizzato per referenziare la pagina in una richiesta HTTP o 
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all'interno della logica dell'applicazione, mentre il titolo e il nome che l'utente 
finale vedra quando la pagina viene visualizzata in un browser. 

• Published: Selezionare Published per far si che la pagina risponda 
automaticamente alle richieste HTTP nel caso in cui il nome della pagina coincida 
con il pathinfo nel messaggio di richiesta. 

• Login Required: Selezionare Login Required se si vuole che l'utente sia obbligato a 
immettere una password prima di poter accedere alia pagina. 

A questo punto si e appreso come iniziare a creare un'applicazione server WebSnap. 
L'esercitazione WebSnap nella sezione successiva descrive come sviluppare 
un'applicazione piu completa. 

Esercitazione WebSnap 



Questa esercitazione fornisce le istruzioni passo passo per la costruzione di 
un'applicazione WebSnap. L'applicazione WebSnap mostra come utilizzare i 
componenti HTML WebSnap per costruire un'applicazione che consente di 
modificare il contenuto di una tabella. Seguire le istruzioni dall'inizio alia fine. Se 
fosse necessaria una piccola pausa, e possibile utilizzare in qualsiasi momento il 
comando File I Save All per salvare il progetto. 

Creazione della nuova applicazione 



Questa sezione descrive come creare una nuova applicazione WebSnap di nome 
Country Tutorial. L'applicazione mostra agli utenti sul web una tabella di 
informazioni su diversi paesi. Gli utenti possono aggiungere e cancellare paesi e 
modificare le informazioni su paesi esistenti. 

Fase 1. Awio di WebSnap application wizard 

1 Eseguire C++Builder e scegliere File I New I Other. 

2 Nella finestra di dialogo New Items, selezionare la pagina WebSnap e scegliere 
WebSnap Application. 

3 Nella finestra di dialogo New WebSnap Application: 

• Selezionare Web App Debugger executable. 

• Nel controllo di editing CoClass Name immettere Country Tutorial. 

• Selezionare Page Module come tipo di componente. 

• Nel campo Page Name scrivere Home. 

4 Fare clic su OK. 

Fase 2. Salvataggio dei file generati e del progetto 

Per salvare il file unit Pascal e il progetto: 
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1 Selezionare File I Save All. 

2 Nella finestra di dialogo Save, selezionare una directory appropriata in cui e 
possibile salvare tutti i file del progetto Country Tutorial. 

3 Nel campo File name immettere HomeU.cpp e fare clic su Save. 

4 Nel campo File name immettere CountryU.cpp e fare clic su Save. 

5 Nel campo File name immettere CountryTutorial.bpr e fare clic su Save. 

Salvare le unit e il progetto nella stessa directory perche l'applicazione cerca il file 
HomeU.html nella stessa directory dell'eseguibile. 

Fase 3. Specifica del titolo dell'applicazione 

II titolo dell'applicazione e il nome visualizzato all'utente finale. Per specificare il 
titolo dell'applicazione: 

1 Scegliere View I Project Manager. 

2 Nel Project Manager espandere CountryTutorial.exe e fare doppio clic sulla voce 
HomeU. 

3 Nella parte superiore della finestra di Object Inspector, selezionare dall'elenco a 
discesa ApplicationAdapter. 

4 Nella pagina Properties, immettere Country Tutorial per la proprieta 
ApplicationTitle. 

5 Fare clic sulla pagina Preview nella finestra dell'editor. II titolo dell'applicazione 
viene visualizzato all'inizio della pagina con il nome della pagina, Home. 

Questa pagina e molto scarna. E possibile migliorarla modificando il file 
HomeU.html, o utilizzando la pagina HomeU.html editor oppure utilizzando un 
editor esterno. Per ulteriori informazioni su come modificare il modello la pagina, 
vedere "Progettazione HTML evoluta" a pagina 34-25. 

Creazione di una pagina CountryTable 



Un modulo pagina Web definisce una pagina pubblicata e agisce anche come 
contenitore per i componenti dei dati. Ogni volta che una pagina web deve essere 
restituita all'utente finale, il modulo pagina Web estrae le informazioni necessarie dai 
componenti di dati in essa contenuti e utilizza quelle informazioni per creare una 
pagina. 

In questa sezione si aggiungera all'applicazione WebSnap un nuovo modulo pagina. 
II modulo pagina aggiungera all'applicazione Country Tutorial una seconda pagina 
visualizzabile. La prima pagina, Home, e stata definita quando si e creata 
l'applicazione. La seconda pagina, di nome countrytable, visualizza la tabella con le 
informazioni dei paesi. 

Fase 1. Aggiunta di un nuovo modulo pagina Web 

Per aggiungere un nuovo modulo di pagina: 
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Scegliere File I New I Other. 

Nella finestra di dialogo New Items, selezionare la pagina WebSnap, scegliere 
WebSnap Page Module e fare clic su OK. 

Nella finestra di dialogo, impostare Producer Type ad AdapterPageProducer. 

Nel campo Page Name immettere Country Table. Notare che anche Title cambia 
man mano che si scrive. 

Lasciare i campi rimanenti con i loro valori predefiniti. 

La finestra di dialogo dovrebbe assomigliare a quella mostrata nella Figure 34.3. 
Fare clic su OK. 

Figura 34.3 Finestra di dialogo New WebSnap Page Module per la pagina CountryTable 



New WebSnap Page Module 



Producer 
Type: 



AdapterPageProducer 



Script Engine: JScripi; 
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Title: | CountryTable 

Published: 1^ Login Required: I - 

Module Options 
Creation: 
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II modulo CountryTable dovrebbe essere visualizzato nell'IDE. Dopo avere salvato il 
modulo, si aggiungeranno al modulo CountryTable i nuovi componenti. 

Fase 2. Salvataggio del nuovo modulo pagina Web 

Salvare la unit nella directory del file di progetto. Quando l'applicazione viene 
eseguita, cerca il file CountryTableU.html nella stessa directory dell'eseguibile. 

1 Scegliere File I Save. 

2 Immettere CountryTableU.cpp nel campo File name e fare clic su Save. 

Aggiunta dei componenti dati al modulo CountryTable 

TTable e TDataSet Adapter sono componenti data-aware; essi forniscono l'accesso a 
dati. TTable fornisce i dati per la tabella HTML. TDataSetAdapter permette alio script 
lato server di accedere al componente TTable. In questa sezione si aggiungeranno 
all'applicazione questi componenti data-aware. 
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Le fasi 1 e 2 seguenti presuppongono che si abbia una certa familiarita con la 
programmazione di database, anche se non e necessaria per completare questa 
esercitazione. WebSnap agisce solo come un'interfaccia (attraverso i componenti 
adapter) per i componenti database. Per maggiori informazioni sulla 
programmazione di database, e possibile fare riferimento alia Parte II di questo 
manuale. 

Fase 1. Aggiunta di componenti data-aware 

1 Scegliere View I Project Manager. 

2 Nel Project Manager espandere CountryTutorial.exe e fare doppio clic sulla voce 
CountryTableU. 

3 Scegliere View I Object Tree View. La finestra Object Tree View diventa attiva. 

4 Selezionare la pagina BDE della Componente palette. 

5 Selezionare un componente Table e aggiungerlo al modulo pagina Web 
CountryTable. 

6 Selezionare un componente Session e aggiungerlo al modulo pagina Web 
CountryTable. II componente Session e necessario perche si sta utilizzando un 
componente BDE (TTable) in un'applicazione multithread. 

7 Selezionare il componente Session, chiamato Sessionl per impostazione 
predefinita, nel modulo pagina Web o nell'Object Tree View. In questo modo si 
visualizzano nell'Object Inspector i valori del componente Session. 

8 Nell'Object Inspector, impostare la proprieta AutoSessionName a true. 

9 Selezionare il componente Table nel modulo pagina Web o nell'Object Tree View. 
In questo modo si visualizzano nell'Object Inspector i valori del componente 
Table. 

10 Nell'Object Inspector, modificare le seguenti proprieta: 

• Impostare la proprieta DatabaseName a DBDEMOS. 

• Nella proprieta Name , immettere Country. 

• Impostare la proprieta TableName a country.db. 

• Impostare la proprieta Active a true. 

Fase 2. Specifica di un campo chiave 

11 campo chiave viene utilizzato per identificare i record all'interno di una tabella. 
Questo diventera importante quando si aggiungera all'applicazione una pagina di 
editing. Per specificare un campo chiave: 

1 Nell'Object Tree View, espandere il nodo Session e DBDemos, quindi selezionare il 
nodo country.db. Questo nodo e il componente Country Table. 

2 Fare clic destro sul nodo country.db e selezionare Fields Editor. 

3 Fare clic destro sulla finestra CountryTable->Country editor e scegliere Add All 
Fields. 
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4 Selezionare il campo Name dall'elenco di campi aggiunti. 

5 Nell'Object Inspector, espandere la proprieta ProviderFlags. 

6 Impostare la proprieta pflnKey a true. 

Fase 3. Aggiunta di un componente adapter 

L'aggiunta dei componenti database e terminata. Ora, per esporre i dati nel TTable 
mediante script lato server, e necessario includere un componente dataset adapter 
(TDataSet Adapter). Per aggiungere un dataset adapter: 

1 Scegliere il componente DataSetAdapter dalla pagina WebSnap della Component 
palette. Aggiungerlo al modulo Web CountryTable. 

2 Modificare le seguenti proprieta nell'Object Inspector: 

• Impostare la proprieta DataSet a Country. 

• Impostare la proprieta Name ad Adapter. 

Una volta terminate), il modulo pagina Web CountryTable dovrebbe assomigliare 
a quello visualizzato nella Figure 34.4. 

Figura 34.4 Modulo pagina Web CountryTable 
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Poiche gli elementi nel modulo non sono visuali, non e importate la posizione in cui 
appaiono nel modulo. Quello che importa e che il modulo contenga gli stessi 
componenti come mostrato in figura. 

Creazione di una griglia per visualizzare i dati 
Fase 1. Aggiunta di una griglia 

Ora, aggiungere una griglia per visualizzare i dati dal database CountryTable: 

1 Scegliere View I Project Manager. 

2 Nel Project Manager, espandere CountryTutorial.exe e fare doppio clic sulla voce 
CountryTableU. 

3 Scegliere View I Object TreeView o fare clic sull'Object Tree View. 

4 Espandere il componente AdapterPageProducer. Questo componente genera lo 
script lato server per creare velocemente una tabella HTML. 

5 Fare clic destro sulla voce WebPageltems e scegliere New Component. 

6 Nella finestra di dialogo Add Web Component, selezionare AdapterForm, quindi 
fare clic su OK. Nell'Object TreeView viene visualizzato un componente 
AdapterForml. 
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7 Fare clic destro su AdapterForml e selezionare New Component. 

8 Nella finestra Add Web Component, selezionare AdapterGrid quindi fare clic su 
OK. Nell'Object Tree View viene visualizzato un componente AdapterGridl. 

9 Nella finestra Object Inspector, impostare la proprieta Adapter ad Adapter. 

Per vedere un'anteprima della pagina, selezionare la pagina Country TableU 
all'inizio dell'editor di codice, quindi selezionare la pagina Preview nella parte 
inferiore. Se la pagina Preview non viene visualizzata, utilizzare nella zona inferiore 
la freccia verso destra per far scorrere le pagine. L'anteprima dovrebbe assomigliare 
alia Figura 34.5. 

Figura 34.5 Pagina CountryTable Preview 
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La pagina Preview mostra come verrebbe visualizzata la pagina finale HTML statica 
in un browser Web. Quella pagina e generata a partire da una pagina dinamica 
HTML che include script. Per vedere una rappresentanza testuale che mostra i 
comandi dello script, selezionare il separatore HTML Script nella zona inferiore della 
finestra dell'editor (vedere la Figura 34.6). 
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Figura 34.6 Pagina CountryTable HTML Script 
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<html> 
<heafl> 
<title> 

<%= Page. Title k> 
</ title> 
-c/jheacl> 
<body> 

<hl><%= Application. Title %.S 



;/hl> 



% if (EndUser: . Logout != null) { %> 
% if (EndUset . DisplayUame \ — 1 ') { k> 
<hl>Welcome <%=EndUset . DisplayName %></lil> 

i ) 4> 

% if (EndUsei:. Logout. Enabled) { %> 

<a href = "<%=EndTJser . Logout . AsHREF%>">Logout</a> 
i ) 4> 

% if (EndUset . Logitirotni. Enabled) { %> 
<a href ^<%^EndUset . LoginForm. AsHREF%>>Login</a> 
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La pagina HTML Script mostra una combinazione di HTML e script. HTML e script 
vengono differenziati nell'editor in base al colore e agli attributi del font. Per 
impostazione predefinita, i marcatori HTML vengono visualizzati in nero e grassetto, 
mentre i nomi dell'attributo HTML vengono visualizzati in nero e i valori 
dell'attributo HTML vengono visualizzati in blu. II codice dello script, che e 
visualizzato tra le parentesi angolari di script <% %>, e colorato in verde. E possibile 
modificare il colore predefinito del font e gli attributi di questi elementi nella pagina 
Color della finestra di dialogo Properties editor, che puo essere visualizzata facendo 
clic destro sull'editor e selezionare Properties. 

Vi sono altre due pagine dell'editor relative all'HTML. La pagina HTML Result 
visualizza il contenuto HTML non formattato dell'anteprima. Notare che le viste 
HTML Result, HTML Script e Preview sono tutte a sola lettura. E possibile utilizzare 
l'ultima pagina dell'editor relativa all'HTML, CountryTable.html, per le modifiche. 

Se si desidera migliorare l'aspetto di questa pagina, e possibile aggiungere del codice 
HTML utilizzando in qualsiasi momento o la pagina CountryTable.html o un editor 
esterno. Per ulteriori informazioni su come modificare il modello di pagina, vedere 
"Progettazione HTML evoluta" a pagina 34-25. 

Fase 2. Aggiunta alia griglia di comandi per I'editing 

Gli utenti possono avere la necessita di aggiornare il contenuto della tabella 
cancellando, inserendo o modificando una riga. Per consentire agli utenti di fare tali 
aggiornamenti, aggiungere dei componenti comando. 

Per aggiungere dei componenti comando: 

1 Nell'Object Tree View per il CountryTable, espandere il componente 
AdapterPageProducer e tutti i suoi rami. 

2 Fare clic destro sul componente AdapterGridl e scegliere Add All Columns. Al 
gruppo di adattatori vengono aggiunte cinque colonne. 
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3 Fare nuovamente clic destro sul componente AdapterGridl e scegliere New 
Component. 

4 Selezionare AdapterCommandColumn e quindi fare clic su OK. Al componente 
AdapterGridlviene aggiunta una voce AdapterCommandColumnl. 

5 Fare clic destro su AdapterCommandColumnl e scegliere Add Commands. 

6 Selezionare contemporaneamente i comandi DeleteRow, EditRow e NewRow, 
quindi fare clic su OK. 

7 Per vedere l'anteprima della pagina, fare clic sulla pagina Preview in fondo 
all'editor di codice. Alia fine di ogni riga nella tabella appaiono ora tre nuovi 
pulsanti (DeleteRow, EditRow e NewRow), come mostrato nella Figura 34.7. 
Quando l'applicazione e in esecuzione, la pressione di uno di questi pulsanti 
esegue l'azione associata. 

Figura 34.7 CountryTable Preview dopo avere aggiunto i comandi di editing 
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Fare clic sul pulsante Save All per salvare l'applicazione prima di continuare. 

Aggiunta di una scheda per I'editing 

A questo punto e possibile creare un modulo pagina Web per gestire la scheda Edit 
per la tabella dei paesi. Gli utenti saranno in grado di modificare i dati 
nell'applicazione CountryTutorial mediante la scheda Edit. Quando l'utente preme i 
pulsanti EditRow o NewRow, viene visualizzata appositamente una scheda Edit. 
Una volta che l'utente ha terminato le operazioni con la scheda Edit, le informazioni 
modificate saranno visualizzate automaticamente nella tabella. 



Fase 1. Aggiunta di un nuovo modulo pagina Web 

Per aggiungere un nuovo modulo pagina Web: 
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1 Scegliere File I New I Other. 

2 Nella finestra di dialogo New Items, selezionare la pagina WebSnap e scegliere 
WebSnap Page Module. 

3 Nella finestra di dialogo, impostare l'opzione Producer Type ad 
AdapterPageProducer. 

4 Impostare il campo Page Name a CountryForm. 

5 Deselezionare la casella Published, in modo che questa pagina non venga 
visualizzata in un elenco di pagine disponibili su questo sito. Alia scheda Edit si 
accede mediante il pulsante Edit e i suoi contenuti dipendono dalla riga della 
tabella dei paesi che deve essere modificato. 

6 Lasciare immutati i valori predefiniti proposti per i campi rimanenti e per le altre 
opzioni. Fare clic su OK. 

Fase 2. Salvataggio del nuovo modulo 

Salvare il modulo nella stessa directory del file di progetto. Quando si esegue 
l'applicazione, essa cerca il file CountryFormU.html nella stessa directory 
dell'eseguibile. 

1 Scegliere File I Save. 

2 Immettere CountryFormU.cpp nel campo File name e fare clic su OK. 

Fase 3. Come rendere CountryTableU accessible al nuovo modulo 

Aggiungere la unit CountryTableU alia direttiva include per consentire al 
componente Adapter l'accesso al modulo. 

1 Scegliere File I Include Unit Hdr. 

2 Scegliere CountryTableU dall'elenco quindi fare clic su OK. 

3 Scegliere File I Save. 

Fase 4. Aggiunta dei campi di immissione 

Aggiungere dei componenti al componente AdapterPageProducer per generare nella 
scheda HTML dei campi di immissione dati. 

Per aggiungere dei campi di immissione: 

1 Scegliere View I Project Manager. 

2 Nella finestra Project Manager, espandere CountryTutorial.exe e fare doppio clic 
sull'elemento CountryFormU. 

3 Nell'Object Tree View espandere il componente AdapterPageProducer, fare clic 
destro su WebPageltems e selezionare New Component. 

4 Selezionare AdapterForm, quindi fare clic su OK. Nell'Object Tree View viene 
visualizzato un elemento Adapter Forml. 

5 Fare clic destro su AdapterForml e selezionare New Component. 
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6 Selezionare AdapterFieldGroup quindi fare clic su OK. Nell'Object Tree View 
viene visualizzato un elemento AdapterFieldGroupl. 

7 Nella finestra Object Inspector, impostare la proprieta Adapter a Country Table- 
adapter. Impostare la proprieta AdapterMode a Edit. 

8 Per vedere l'anteprima della pagina, fare clic sulla pagina Preview in fondo 
all'editor del codice. L'anteprima dovrebbe somigliare a quella visualizzata nella 
Figure 34.8. 

Figura 34.8 Anteprima il CountryForm 
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Fase 5. Aggiunta di pulsanti 

Aggiungere dei componenti al componente AdapterPageProducer per generare nella 
scheda HTML i pulsanti per l'inoltro. Per aggiungere i componenti: 

1 Nell'Object Tree View espandere il componente AdapterPageProducer e tutti i suoi 
rami. 

2 Fare clic destro su AdapterForml e scegliere New Component. 

3 Selezionare AdapterCommandGroup quindi fare clic su OK. Nell'Object 
TreeView viene visualizzato un elemento AdapterCommandGroupl a. 

4 Nell'Object Inspector, impostare la proprieta DisplayComponent ad 
AdapterFieldGroupl. 

5 Fare clic destro sull'elemento AdapterCommandGroupl e scegliere Add 
Commands. 

6 Selezionare contemporaneamente i comandi Cancel, Apply e Refresh Row, quindi 
fare clic su OK. 

7 Per vedere l'anteprima della pagina, fare clic sulla pagina Preview in fondo alia 
finestra dell'editor del codice. Se l'anteprima non visualizza la pagina 
CountryForm, fare clic sulla pagina Code e quindi fare nuovamente clic sulla 
pagina Preview. L'anteprima dovrebbe somigliare a quella visualizzata nella 
Figure 34.9. 
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Figura 34.9 CountryForm con i pulsanti di inoltro 
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Fase 6. Collegamento di azioni della scheda con la pagina della griglia 

Quando l'utente fa clic su un pulsante, viene eseguita un'azione dell'adapter il quale 
a sua volta esegue l'azione descritta. Per apecificare quale pagina visualizzare dopo 
l'esecuzione dell'azione dell'adapter: 

1 Nell'Object Tree View, espandere AdapterCommandGroupl per visualizzare le 
voci CmdCancel, CmdApply e CmdRefreshRow. 

2 Selezionare CmdCancel. Nella finestra dell'Object Inspector, scrivere 
CountryTable nella proprieta PageName. 

3 Selezionare CmdApply. Nella finestra dell'Object Inspector, scrivere 
CountryTable nella proprieta PageName. 

Fase 7. Collegamento delle azioni della griglia con la pagina della scheda 

Premendo un pulsante nella griglia viene eseguita un'azione dell'adapter. Per 
specificare quale pagina deve essere visualizzata in risposta all'azione dell'adapter: 

1 Scegliere View I Project Manager. 

2 Nel Project Manager, espandere CountryTutorial.exe e fare doppio clic sulla voce 
CountryTableU. 

3 Nell'Object Tree View, espandere il componente AdapterPageProducer e tutti i suoi 
rami per visualizzare le voci CmdNewRow, CmdEditRow e CmdDeleteRow. 
Queste voci vengono visualizzate sotto la voce AdapterCommandColumnl. 

4 Selezionare CmdNewRow. Nell'Object Inspector, immettere CountryForm nella 
proprieta PageName. 

5 Selezionare CmdEditRow. Nell'Object Inspector, immettere CountryForm nella 
proprieta PageName. 

Per verificare che l'applicazione funzioni e che tutti i pulsanti eseguano qualche 
azione, eseguire l'applicazione. Per apprendere come eseguire l'applicazione, vedere 
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"Esecuzione dell'applicazione ultimata" a pagina 34-23. Quando si esegue 
l'applicazione, si manda in esecuzione un server. Per controllare che l'applicazione 
funzioni, e necessario visualizzarlo in un browser Web. E possibile fare cio 
avviandolo dal Web Application debugger. 

Non sara visualizzata alcuna indicazione relativa a errori di database, come un tipo 
non valido. Ad esempio, provare ad aggiungere nel campo Area un nuovo paese con 
un valore non ammesso (ad esempio, 'abc. 

Esecuzione dell'applicazione ultimata 



Per eseguire l'applicazione ultimata: 

1 Scegliere Run I Run. Viene visualizzata una scheda. Le Web Application compilate 
come eseguibili di Web App Debugger sono server COM e la scheda che si vede e 
la finestra console del server COM. La prima volta che si esegue il progetto, esso 
registra l'oggetto COM a cui Web App Debugger pud accedere direttamente. 

2 Scegliere Tools I Web App Debugger. 

3 Fare clic sul link dello URL predefinito per visualizzare la pagina Serverlnfo. La 
pagina Serverlnfo visualizza i nomi di tutti gli eseguibili Web Application 
Debugger registrati. 

4 Scegliere nell'elenco a discesa Country Tutorial e fare clic sul pulsante Go. 

II browser visualizzera l'applicazione Country Tutorial. Fare clic sul link 
CountryTable per vedere la pagina CountryTable. 

Aggiunta della notifica degli errori 



A questo punto dello sviluppo, l'applicazione non visualizza all'utente alcun errore. 
Ad esempio, se si immettono delle lettere nel campo Area del record di un paese, non 
verra visualizzato alcun avvertimento del fatto che si e verificato un errore. In questa 
sezione si aggiungera un componente AdapterErrorList per visualizzare gli errori 
che si verificano durante l'esecuzione delle azioni dell'adapter che modificano la 
tabella dei paesi. 

Fase 1. Aggiunta alia griglia del supporto per gli errori 

Per aggiungere alia griglia il supporto per gli errori: 

1 Nell'Object Tree View di CountryTable, espandere il componente 
AdapterPageProducer e tutti i suoi rami in modo da visualizzare Adapter Forml. 

2 Fare clic destro su AdapterForml e scegliere New Component. 

3 Selezionare dall'elenco AdapterErrorList, quindi fare clic su OK. Nell'Object 
TreeView viene visualizzato un elemento AdapterErrorListl. 

4 Spostare AdapterErrorListl prima di AdapterGridl (o trascinandolo o utilizzando 
la freccia verso l'alto nella barra strumenti dell'Object TreeView). 
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5 Nell'Object Inspector, impostare la proprieta Adapter ad Adapter. 

Fase 2. Aggiunta alia scheda del supporto per gli errori 

Per aggiungere alia scheda il supporto per gli errori: 

1 Nell'Object Tree View di CountryForm, espandere il componente 
AdapterPageProducer e tutti i suoi rami in modo da visualizzare Adapter Forml. 

2 Fare clic destro su AdapterForml e scegliere New Component. 

3 Selezionare dall'elenco AdapterErrorList, quindi fare clic su OK. Nell'Object 
TreeView viene visualizzato un elemento AdapterErrorListl. 

4 Spostare AdapterErrorListl prima di AdapterFieldGroupl (o trascinandolo o 
utilizzando la freccia verso l'alto nella barra strumenti dell'Object TreeView). 

5 Nell'Object Inspector, impostare la proprieta Adapter a Country Table-> Adapter. 

Fase 3. Verifica del meccanismo di segnalazione errori 

Per osservare il meccanismo di segnalazione errori, e necessario fare prima una 
piccola modifica nell'IDE di C++Builder. Selezionare Tools I Debbugger Options. 
Nella pagina Language Exceptions, verificare che la casella Stop on Delphi 
Exceptions non sia selezionata, cosa che permettera all'applicazione di continuare nel 
caso vengano rilevate eccezioni. A questo punto, per verificare gli errori della griglia: 

1 Eseguire l'applicazione e, utilizzando Web Application Debugger, passare alia 
pagina Country Table. Per informazioni sull'operazione, vedere "Esecuzione 
dell'applicazione ultimata" a pagina 34-23. 

2 Aprire un'altra finestra del browser e passare alia pagina Country Table. 

3 Fare clic sul pulsante DeleteRow sulla prima riga della griglia. 

4 Senza aggiornare il secondo browser, fare clic sul pulsante DeleteRow sulla prima 
riga della griglia. 

Prima della griglia viene viusalizzato il messaggio di errore "Row not found in 
Country". 

Per verificare gli errori di scheda: 

1 Eseguire l'applicazione e, utilizzando Web Application debugger, passare alia 
pagina Country Table. 

2 Fare clic sul pulsante EditRow. Viene visualizzata la pagina CountryForm. 

3 Modificare il campo Area in 'abc' e fare clic sul pulsante Apply. 

Sopra al primo campo verra visualizzato il messaggio di errore ("Invalid value for 
field 'Area'". 

A questo punto l'esercitazione WebSnap e stata completata. Prima di continuare si 
potrebbe voler selezionare di nuovo la casella di controllo Stop on Delphi Exceptions. 
Inoltre, salvare l'applicazione scegliendo File I Save All in modo che l'applicazione 
ultimata sia disponibile e consultabile in future 
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Progettazione HTML evoluta 



Utilizzando gli adattatori e i produttori di pagina di adapter, WebSnap semplifica la 
creazione di pagine HTML con supporto di script nell'applicazione per Web server. 
Utilizzando gli strumenti di WebSnap e possibile creare un'interfaccia Web per i dati 
dell'applicazione, in grado di soddisfare tutte le proprie esigenze. Una potente 
funzione di WebSnap, tuttavia, e la capacita di incorporare nell'applicazione le 
capacita di progettazione per Web di altre sorgenti. Questa sezione tratta alcune 
strategie per espandere il processo di progettazione e di manutenzione del Web 
server includendo altri strumenti e membri del team non programmatori. 

I prodotti finali per lo sviluppo WebSnap sono l'applicazione server e i modelli 
HTML per le pagine prodotte dal server. I modelli includono una miscela di scripting 
e di HTML. Una volta generati nella fase iniziale, possono essere modificati in 
qualunque momento utilizzando un qualsiasi strumento HTML. (Sarebbe meglio 
utilizzare uno strumento che supporti marcatori di script incorporati, come Microsoft 
FrontPage, per assicurarsi che l'editor non danneggi casualmente lo script). La 
capacita di modificare le pagine dei modelli esternamente all'IDE puo essere 
utilizzata in vari modi. 

Ad esempio, gli sviluppatori C++ Builder possono modifcare i modelli HTML in 
progettazione utilizzando un qualsiasi editor esterno. Cio permette per utilizzare 
runzioni di f ormattazione e di scripting evolute che possono essere presenti in un 
editor HTML esterno ma non in C++ Builder. Per attivare un editor HTML esterno 
dall'IDE, fare quanto segue: 

1 Dal menu principale, selezionare Tools I Environment Options. Nella finestra di 
dialogo Environment Options, fare clic sulla pagina Internet. 

2 Nel riquadro Internet File Types, selezionare HTML e fare clic sul pulsante Edit 
per visualizzare la finestra di dialogo Edit Type. 

3 Nel riquadro Edit Action, selezionare un'azione associata all'editor HTML. Ad 
esempio, per selezionare l'editor HTML predefinito nel sistema, scegliere Edit 
dall'elenco a discesa. Fare clic su OK due volte per chiudere le finestre di dialogo 
Edit Type e Environment Options. 

Per modificare un modello HTML, aprire la unit che contiene quel modello. Nella 
finestra Edit, fare clic destro e selezionare Html Editor dal menu contestuale. L'editor 
HTML visualizza il modello da modificare in una finestra differente. L'editor viene 
eseguito in modo indipendente dell'IDE; una volta terminato, salvare il modello e 
chiudere l'editor. 

Dopo la distribuzione delprodotto, si potrebbe voler modificare l'aspetto delle 
pagine HTML definitive. E probabile che il team di sviluppo software non sia 
nemmeno responsabile del formato della pagina finale. Tale compito potrebbe essere 
affidato, per esempio, a un Web page designer nell'organizzazione. E possibile che i 
Web page designer non abbiano alcuna esperienza di sviluppo in C++ Builder. 
Fortunatamente, non e necessario che ne abbiano. Essi possono modificare i modelli 
di pagina in qualsiasi punto del ciclo di sviluppo e di manutenzione del prodotto, 
senza mai modificare il codice sorgente. In tale modo, i modelli HTML di WebSnap 
possono rendere piu efficienti lo sviluppo e la manutenzione del server. 
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Trattamento dello script lato server nei file HTML 



II codice HTML nei modelli di pagina puo essere modificato in qualsiasi momento 
del ciclo di sviluppo. Tuttavia, lo scripting lato server deve essere affrontato in modo 
diverse E sempre possibile modificare lo script lato server incluso nei modelli 
esternamente a C++ Builder, ma non e una cosa consigliabile per le pagine generate 
da un adapter produttore di pagine. L'adapter produttore di pagine e diverso dai 
normali produttori di pagine per il fatto che, in esecuzione, puo modificare lo 
scripting lato server incluso nei modelli di pagina. Puo essere difficile predire come 
agira lo script se un altro script viene aggiunto dinamicamente. Se si vogliono trattare 
direttamente gli script, accertarsi che il modulo pagina Web contenga un produttore 
di pagine e non un adapter produttore di pagine. 

Se si ha un modulo pagina Web che utilizza un adapter produttore di pagine, e 
possibile convertirlo in modo che utilizzi invece un normale produttore di pagine nei 
seguente modo: 

1 Copiare nei modulo che si desidera convertire (supponendo che si chiami 
ModuleName) tutte le informazioni dalla pagina HTML Script sulla pagina 
ModuleName.html, sostituendo tutte le informazioni che precedentemente 
conteneva. 

2 Trascinare un produttore di pagine (presente sulla pagina Internet della 
Component palette) sul modulo pagina Web. 

3 Impostare la proprieta ScriptEngine del produttore di pagine in modo che 
corrisponda a quello dell'adapter produttore di pagine di cui prendera il posto. 

4 Modificare il produttore di pagine nei modulo pagina Web dall'adapter 
produttore di pagine nei nuovo produttore di pagine. Fare clic sulla pagina 
Preview per verificare che i contenuti della pagina restino invariati. 

5 A questo punto l'adapter produttore di pagine e stato scavalcato. E possibile 
cancellarlo dal modulo pagina Web. 

Supporto per il login 



Molte applicazioni per Web server richiedono il supporto per il login. Ad esempio, 
un'applicazione server puo richiedere che un utente esegua il login prima di 
concedere l'accesso ad alcune parti di un sito Web. Le pagine possono avere un 
aspetto diverso per i diversi utenti; il login puo essere necessario per permettere al 
server Web di inviare le pagine corrette. Inoltre, poiche i server hanno limitazioni 
fisiche nei cicli di memoria e di processore, le applicazioni server hanno bisogno 
talvolta della capacita di limitare il numero di utenti in un dato momento. 

Con WebSnap, l'inclusione nell'applicazione per Web server del supporto per il login 
e abbastanza semplice e diretta. In questa sezione, si apprendera come e possibile 
aggiungere il supporto per il login, sia progettandolo dall'inizio del processo di 
sviluppo sia aggiungendolo a un'applicazione esistente. 
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Aggiunta del supporto per il login 



Per implementare il supporto per login, e necessario assicurarsi che il modulo Web 
application abbia i seguenti componenti: 

• Un servizio di elenco utenti (un oggetto di tipo TWebUserList), che contiene i nomi 
degli utente, le password e i permessi accordati agli utenti del server 

• Un servizio per le sessioni (TSessionsService), che memorizza le informazioni sugli 
utenti attualmente connessi al server 

• Un adapter per utente finale (TEndUserSessionAdapter) che gestisce le azioni 
associate alia procedura di login 

Quando si comincia a creare l'applicazione per Web server, e possibile aggiungere 
questi componenti utilizzando la finestra di dialogo New WebSnap Application. Fare 
clic sul pulsante Components su quella finestra di dialogo per visualizzare la finestra 
di dialogo New Web App Components. Selezionare le caselle End User Adapter, 
Sessions Service e Web User List. Nel menu a discesa accanto alia casella End User 
Adapter, selezionare TEndUserSessionAdapter in modo da selezionare il tipo di 
adapter per utente finale, (la scelta predefinita, TEndUser Adapter, non e appropriata 
per il supporto del login perche non puo tracciare l'utente corrente). Una volta 
terminato, la finestra di dialogo dovrebbe assomigliare a quello visualizzata di 
seguito. Fare clic su OK due volte per chiudere le finestre di dialogo. II modulo Web 
application web ora ha i componenti necessari per il supporto del login. 

Figura 34.1 Finestra di dialogo Web App Components con leopzioni per supporto del login selezionate 
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Se si aggiunge il supporto per il login a un modulo Web application esistente, e 
possibile trascinare questi componenti direttamente nel modulo prelevandoli dalla 
pagina WebSnap della Component palette. II modulo Web application si configurera 
automaticamente. 

II servizio per le sessioni e l'adapter per utente finale potrebbero non richiedere 
particolare attenzione durante la fase di progettazione a diffrenza invece dell'elenco 
utenti Web. E possibile aggiungere utenti predefiniti e impostarne i diritti di lettura/ 
modifica tramite l'editor del componente WebUserList. Fare doppio clic sul 
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componente per visualizzare un editor che permette di impostare i nomi degli utenti, 
le password e i diritti di accesso. Per ulteriori informazioni su come configurare i 
diritti di accesso, vedere "Diritti di accesso degli utenti" on page 34-31. 

Utilizzo del servizio per le sessioni 



II servizio per le sessioni, che e un oggetto del tipo TSessionsService, tiene traccia 
degli utenti registrati nell'applicazione per Web server. II servizio per le sessioni si 
incarica di assegnare una sessione diversa ad ogni utente e di associare a un utente 
coppie di tipo nome/valore (come un nome utente). 

Le informazioni contenute in un servizio per le sessioni sono conservate nella 
memoria dell'applicazione. Pertanto, l'applicazione per Web server deve essere 
tenuta in esecuzione fra le varie richieste affinche il servizio per le sessioni funzioni 
correttamente. Alcuni tipi di applicazioni server, come le CGI, terminano tra una 
richiesta e l'altra. 

Se si vuole che l'applicazione supporti il login, assicurarsi di utilizzare un tipo di 
server che non termini tra un richiesta e l'altra. Se il progetto produce un eseguibile 
Web App debugger, e necessario fare in modo che l'applicazione venga eseguita in 
background prima che riceva una richiesta di pagina. In caso contrario terminera 
dopo ogni richiesta di pagina e gli utenti non saranno mai in grado di ottenere la 
pagina di login. 

Nel servizio per le sessioni ci sono due proprieta importanti che e possibile utilizzare 
per modificare il comportamento predefinito del server. La proprieta MaxSessions 
specifica quanti utenti possono essere registrati nel sistema in un dato momento. II 
valore predefinito per MaxSessions e -1, che non pone alcuna limitazione software al 
numero di utenti consentiti. Naturalmente, l'hardware del server potrebbe disporre 
di poca memoria o servire gli utenti in modo ciclico, il che puo influire 
negativamente sulle prestazioni del sistema. Se si pensa che il numero eccessivo di 
utenti potrebbe sovraccaricare il server, accertarsi di impostare MaxSessions a un 
valore appropriate 

La proprieta DefaultTimeout specifica il periodo di timeout predefinito in minuti. 
Dopo che sono trascorsi DefaultTimeout minuti senza alcuna attivita da parte 
dell'utente, la sessione viene terminata automaticamente. Se l'utente aveva eseguito 
il login, tutte le informazioni di login vanno perdute. II valore predefinito e 20. E 
possibile ridefinire il valore predefinito in qualsiasi sessione modificandone la 
proprieta TimeoutMinutes. 

Pagine di login 



Naturalmente, l'applicazione ha bisogno anche di una pagina di login. Gli utenti 
immettono il loro nome utente e la loro password per l'autenticazione, o mentre 
tentano di accedere a una pagina con accesso limitato o prima di tale tentativo. 
L'utente puo anche specificare quale pagina ricevere una volta completata 
l'autenticazione. Se il nome utente e la password sono uguali a quelli di un utente 
nell'elenco Web user, l'utente acquisisce i diritti di accesso appropriati e viene 
indirizzato alia pagina specificata nella pagina di login. Se l'utente non e autenticato, 
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e possibile visualizzare di nuovo la pagina di login (azione predefinita) oppure fare 
eseguire un'altra azione. 

Fortunatamente, WebSnap semplifica la creazione di una semplice pagina di login 
utilizzando un modulo pagina Web e l'adapter produttore di pagine. Per creare una 
pagina di login, iniziare creando un nuovo modulo pagina Web. Selezionare File I 
New I Other per visualizzare la finestra di dialogo New Items, quindi selezionare 
dalla pagina WebSnap l'opzione Page Module. Selezionare AdapterPageProducer 
come tipo di produttore di pagina. Compilare le altre opzioni nel modo desiderata. 
Come nome della pagina di login si puo usare Login. 

A questo punto si dovrebbero aggiungere i classici campi presenti in una pagina di 
login: un campo per il nome utente, uno per la password, una casella di selezione per 
selezionare la pagina da ricevere dopo aver effettuato il login e un pulsante Login che 
trasmette la pagina ed esegue l'autenticazione dell'utente. Per aggiungere questi 
campi: 

1 Aggiungere al modulo pagina Web appena creato un componente 
LoginFormAdapter (che e possibile trovare sulla pagina WebSnap della 
Component palette). 

2 Fare doppio clic sul componente AdapterPageProducer per visualizzare una finestra 
per l'editing della pagina web. 

3 Fare clic destro su AdapterPageProducer nel riquadro superiore di sisnistra e 
selezionare New Component. Nella finestra di dialogo Add Web Component 
selezionare AdapterForm e fare clic su OK. 

4 Aggiungere un AdapterFieldGroup ad AdapterForm. (Fare clic destro su 
AdapterForm nel riquadro superiore di sisnistra e selezionare New Component. 
Nella finestra di dialogo Add Web Component selezionare AdapterFieldGroup e 
fare clic su OK.) 

5 Passare all'Object Inspector e impostare la proprieta Adapter di AdapterFieldGroup a 
LoginFormAdapter. I campi UserName, Password e NextPage dovrebbero venire 
visualizzati automaticamente nella pagina Browser dell'editor della pagina web. 

Fatto cio, WebSnap si incarica della maggior parte del lavoro con poche semplici 
operazioni. Sulla pagina di login manaca ancora un pulsante Login che trasmetta le 
informazioni sulla scheda per l'autenticazione. Per aggiungere un pulsante Login: 

1 Aggiungere un AdapterCommandGroup ad AdapterForm. 

2 Aggiungere un Adapter ActionButton ad AdapterCommandGroup. 

3 Fare clic su Adapter ActionButton (elencato nel riquadro superiore di destra 
dell'editor della pagina web) e, utilizzando l'Object Inspector, modificarne la 
proprieta ActionName in Login. E possibile vedere un'anteprima della pagina di 
login nella pagina Browser dell'editor della pagina web. 

L'editor della pagina web dovrebbe sembrare assomigliare a quello visualizzato di 
seguito. 



Creazione di applicazioni Web Server con WebSnap 34-29 



Supporto per il login 

Figura 34.1 1 Un esempio di pagina di login visto nell'editor della pagina web 
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Se sotto AdapterFieldGroup non viene visualizzato il pulsante, accertarsi che 
AdapterCommandGroup sia elencato dopo AdapterFieldGroup nell'editor della pagina 
web. Se e visualizzato prima, selezionare AdapterCommandGroup e fare clic sulla 
freccia verso il basso sull'editor della pagina web. (Di solito, gli elementi delle pagine 
web vengono visualizzati in verticale nello stesso ordine con cui sono visualizzati 
nell'editor della pagina web.) 

Prima che la pagina di login diventi funzionale e necessaria un'altra operazione. E 
necessario specificare qual e la pagina di login nell'adapter della sessione per l'utente 
finale. Per fare cio, selezionare il componente EndUserSessionAdapter nel modulo Web 
application. Nell'Object Inspector, modificare la proprieta LoginPage nel nome della 
pagina di login. Ora la pagina di login e abilitata per tutte le pagine nell'applicazione 
per Web server. 

Impostazione delle pagine in modo che richiedano il login 



Una volta che si ha una pagina di login funzionante, e necessario che le pagine a cui e 
necessario accedere in modo controllato richiedano il login. II modo piu semplice per 
fare in modo che una pagina richieda il login consiste nel progettare tale pagina con 
quel requisite All'atto delle creazione del modulo pagina Web, nella sezione Page 
della finestra di dialogo New WebSnap Page Module, spuntare la casella Login 
Required. 

Se si crea una pagina senza richiedere il login, e possibile modificarla 
successivamente. Per fare in modo che venga richiesto il login dopo aver creato un 
modulo pagina Web: 

1 Aprire nell'editor il codice sorgente del file associato al modulo pagina Web. 

2 Scorrere il sorgente fino alia dichiarazione della funzione statica Weblnit. 
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3 Eliminare il commento dalla parte wpLoginRequired dell'elenco di parametri 
rimuovendo i simboli /* e */ che lo racchiudono. La funzione Weblnit dovrebbe 
somigliare a quello visualizzata di seguito: 

static TWebPagelnit Weblnit L_classid(TAdapterPageProducerPage3) , crOnDemand, caCache, 
Page-Access « wpPublished « wpLoginRequired, ".html", "", "", "", ""); 

Per eliminare da una pagina la necessita di effettuare il login, invertire il processo e 
commentare di nuovo la sezione wpLoginRequired della dichiarazione. 

E possibile utilizzare lo stesso procedimento per rendere pubblica la pagina o meno. 
E sufficiente aggiungere o rimuovere i segni di commento che racchiudono la sezione 
wpPublished in base alle proprie necessita. 

Diritti di accesso degli utenti 



I diritti di accesso degli utenti sono una parte importante di qualsiasi applicazione 
per Web server. E necessario essere in grado di controllare chi puo visualizzare e 
modificare le informazioni che il server fornisce. Ad esempio, si supponga di creare 
un'applicazione server per gestire le vendite al dettaglio online. E normale consentire 
agli utenti di visualizzare gli elementi nel catalogo, ma non si deve consentire che 
siano in grado di modificare i prezzi! Chiaramente, i diritti di accesso sono un 
argomento importante. 

Per fortuna, WebSnap consente di controllare l'accesso alle pagine e ai contenuti del 
server in numerosi modi. Nelle sezioni precedenti, si e visto come e possibile 
controllare accesso alle pagine tramite la richiesta di login. Vi sono anche altre 
possibilita. Ad esempio: 

• E possibile visualizzare i campi dati in una casella di modifica agli utenti con gli 
appropriati diritti di modifica; altri utenti vedranno il contenuto di campo, ma non 
avranno la possibilita di modificarli. 

• E possibile nascondere determinati campi agli utenti che non hanno i necessari 
diritti di accesso in visualizzazione. 

• E possibile impedire agli utenti non autorizzati di ricevere determinate pagine. 
In questa sezione viene spiegato come implementare questi comportamenti. 

Visualizzazione dinamica di campi come caselle di testo o di modifica 

Se si utilizza l'adapter produttore di pagine, e possibile modificare l'aspetto degli 
elementi della pagina per gli utenti con diversi diritti di accesso. Ad esempio, la 
demo Biolife (presente nella subdirectory WebSnap della directory Demos) contiene 
una pagina di scheda che mostra tutte le informazioni per una certa specie. La scheda 
viene visualizzata quando l'utente fa clic su un pulsante Details sulla griglia. Un 
utente connesso come Will vede i dati presentati come testo. A Will non e consentito 
modificare i dati, e pertanto la scheda non gli offre alcun meccanismo per farlo. 
L'utente Ellen ha i diritti di modifica, e pertanto, quando Ellen visualizza la pagina 
della scheda, vede una serie di caselle di modifica che le permettono di modificare il 
contenuto dei campi. Un tale utilizzo dei diritti di accesso puo evitare di creare 
ulteriori pagine. 
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L'aspetto di alcuni elementi della pagina, come TAdapterDisplayField e 
TAdapterDisplay Column, e determinate dalla proprieta ViewMode. Se ViewMode e 
impostato a vmToggleOn Access, l'elemento della pagina sara visualizzato agli utenti 
con diritti di modifica come una casella di modifica. Gli utenti senza diritti di 
modifica vedranno solo il testo. Impostare la proprieta ViewMode a vmToggleOnAccess 
per fare in modo che l'aspetto e la funzione dell'elemento della pagina venga stabilito 
dinamicamente. 

Un elenco di utenti Web e un elenco di oggetti TWebUserListltem, uno per ogni utente 
che puo effettuare il login al sistema. Le autorizzazioni agli utenti sono memorizzate 
nella proprieta AccessRights del rispettivo elemento dell'elenco di utenti Web. 
AccessRights e una stringa di testo, pertanto si e liberi di specificare le autorizzazioni 
nel modo preferito. Creare un nome per ogni tipo di diritto di accesso desiderata 
all'applicazione server. Se si vuole che un utente abbia piu diritti di accesso, separare 
gli elementi nell'elenco con uno spazio, con un punto e virgola o con una virgola. 

I diritti di accesso per i campi sono controllati dalle ripettive proprieta View Access e 
Modify Access. ViewAccess memorizza il nome dei diritti di accesso necessari per 
visualizzare un certo campo. Modify Access impone i diritti di accesso necessari per 
modificare i dati di campo. Queste proprieta appaiono in due punti: in ogni campo e 
nell'oggetto adapter che li contiene. 

II controllo dei diritti di accesso e un processo in due fasi. Nel momento in cui deve 
decidere l'aspetto di un campo in una pagina, l'applicazione per prima cosa controlla 
i diritti di accesso del campo. Se il valore e una stringa vuota, allora l'applicazione 
controlla i diritti di accesso dell'adapter che contiene il campo. Se anche la proprieta 
dell'adapter e vuota, l'applicazione seguira il suo comportamento predefinito. Per gli 
accessi in modifica, il comportamento predefinito e quello di consentire le modifiche 
a tutti gli utenti nell'elenco utenti Web la cui proprieta AccessRights non e vuota. Per 
gli accessi in visualizzazione, l'autorizzazione viene concessa automaticamente se 
non e stato specificato alcun diritto di accesso in visualizzazione. 

Occultamento dei campi e del loro contenuto 

E possibile nascondere il contenuto di un campo agli utenti che non hanno gli 
opportuni diritti di visualizzazione. Per prima cosa si imposta la proprieta 
ViewAccess del campo in modo che corrisponda all'autorizzazione che si desidera 
assegnare agli utenti. Quindi, ci si deve accertare che il ViewAccess per l'elemento 
della pagina del campo sia impostato a vmToggleOnAccess. L'intestazione di campo 
sara visualizzata, ma il valore del campo non lo sara. 

Naturalmente, spesso e meglio nascondere tutti i riferimenti al campo quando un 
utente non ha le autorizzazioni di visualizzazione. Per fare cio, impostare 
HideOptions dell'elemento di pagina del campo in modo da includere 
hoHideOnNoDisplayAccess. Non saranno visualizzati ne l'intestazione ne i contenuti 
del campo. 

Come evitare I'accesso alia pagina 

Si potrebbe decidere che alcune pagine non devono essere accessibili agli utenti non 
autorizzati. Per concedere i diritti di accesso prima di visualizzare le pagine, 



34-32 Guida alia programmazione 



Scripting lato server in WebSnap 

modificare la dichiarazione della funzione Weblnit del modulo. Questa funzione 
appare nel codice sorgente del modulo. 

La funzione Weblnit accetta fino a 9 argomenti. Di solito WebSnap ne lascia quattro 
impostati ai valori predef initi (stringhe vuote), pertanto di solito la chiamata 
assomiglia alia seguente: 

static TWebPagelnit Weblnit L_classid(TAdapterPageProducerPage3) , crOnDemand, caCache, 
PageAccess « wpPublished /* « wpLoginRequired */, ".html", "", "", "", ""); 

Per controllare le autorizzazioni prima di consentire l'accesso, e necessario fornire nel 
nono parametro la stringa per la necessaria autorizzazione. Ad esempio, si supponga 
che il nome dell'autorizzazione sia Access. Ecco come si dovrebbe modificare la 
funzione Weblnit: 

static TWebPagelnit Weblnit ( classid(TAdapterPageProducerPage3) , crOnDemand, caCache, 

PageAccess « wpPublished /* « wpLoginRequired */, ".html", "", "", "", "Access"); 

L'accesso alia pagina sara negato a chiunque e privo dell'autorizzazione Access. 

Scripting lato server in WebSnap 



I modelli dei produttori di pagine possono includere linguaggi di scripting come 
JScript o VBScript. II produttore di pagine esegue lo script in risposta a una richiesta 
di contenuti del produttore. Poiche l'applicazione per Web server valuta lo script, 
viene detta script lato server, a differenza dello script lato client (che viene valutato 
dal browser). 

Questa sezione fornisce una panoramica concettuale dello scripting lato server e di 
come viene utilizzato dalle applicazioni WebSnap. L'appendice "Guida di 
riferimento alio scripting lato server di WebSnap" contiene informazioni molto piu 
dettagliate sugli oggetti script e sulle rispettive proprieta e metodi. La si puo 
considerare come una guida di riferimento alle API per lo scripting lato server, simile 
alle descrizioni degli oggetto di C++Builder incluse nei file della Guida. L'appendice 
contiene anche esempi dettagliati di script che mostrano esattamente come si puo 
utilizzare lo script per generare pagine HTML. 

Benche lo scripting lato server sia una parte importante di WebSnap, non e 
necessario utilizzare gli script nelle applicazioni WebSnap. Lo scrip viene utilizzato 
per la generazione del codice HTML e per null'altro. Permette di inserire in una 
pagina HTML i dati dell'applicazione. Infatti, quasi tutte le proprieta esposte dagli 
adattatori e altri oggetti abilitati alio script sono a sola lettura. Lo script lato server 
non viene utilizzato per modificare i dati dell'applicazione, che vengono gestiti da 
componenti e da gestori di evento scritti in Pascal o in C++. 

Esistono altri modi per inserire i dati dell'applicazione in una pagina HTML. Se si 
preferisce, e possibile utilizzare i marcatori trasparenti di Web Broker o qualche altra 
soluzione basata su marcatori. Ad esempio, diversi progetti nella cartella Examples \ 
WebSnap di C++ Builder utilizzano XML e XSL invece dello scripting. Senza 
scripting, tuttavia, si sara costretti a scrivere la maggior parte della logica della 
generazione HTML in C++, il che allunghera i tempi di sviluppo. 
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Lo scripting utilizzato in WebSnap e orientato agli oggetti e supporta la logica 
condizionale e i cicli, il che puo semplificare notevolmente l'attivita di generazione 
delle pagine. Ad esempio, le pagine possono includere un campo dati che puo essere 
modificato da alcuni utenti ma non da altri. Con lo scripting, la logica condizionale 
puo essere inclusa nelle pagine modello che visualizzeranno una casella di modifica 
per gli utenti autorizzati e del semplice testo per altri. Con un approccio basato su 
marcatori, e necessario programmare tale processo decisionale nel codice sorgente 
che genera il codice HTML. 

Active scripting 



Per implementare lo script lato server, WebSnap si basa su active scripting. Active 
scripting e una tecnologia creata da Microsoft per consentire l'uso di un linguaggio di 
scripting con gli oggetti dell'applicazione attaraverso interfacce COM. Microsoft 
prevede due linguaggi di active scripting, VBScript e JScript. II supporto per altri 
linguaggi e disponibile tramite produttori terzi. 

Motore di script 



La proprieta ScriptEngine del produttore di pagine identifica il motore di active 
scripting che valuta lo script all'interno di un modello. L'impostazione predefinita e 
quella di supportare JScript, ma puo anche supportare altri linguaggi di scripting 
(come VBScript). 

Gli adattatori di WebSnap sono progettati per produrre JScript. Per altri linguaggi di 
scripting sara necessario fornire alio script la logica di generazione. 

Blocchi di script 



I blocchi di script, che appaiono nei modelli HTML, sono delimitati da <% e da %>. II 
motore di script valuta qualsiasi testo interno al blocco di script. II risultato diventa 
parte dei contenuti del produttore di pagine. II produttore di pagine scrive il testo 
esterno a un blocco di script dopo avere tradotto gli eventuali marcatori trasparenti 
incorporati. I blocchi di script possono anche includere testo, consentendo alia logica 
condizionale e ai cicli di determinare il testo di output. Ad esempio, il seguente 
blocco JScript genera un elenco di cinque righe numerate: 

<ul> 

<% for (i=0;i<5;i++) { %> 
<li>Item <%=i %></li> 
<% } %> 
</ul> 

(Til delimitatore <%= e l'abbreviazione di Response. Write) 
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Gli sviluppatori possono sfruttare le funzionalita di WebSnap per generare 
automaticamente script. 

Modelli di wizard 

Quando si crea un nuovo modulo WebSnap application o pagina, i wizard di 
WebSnap presentano un campo Template che viene utilizzato per selezionare il 
contenuto iniziale del modello del modulo pagina. Ad esempio, il modello Default 
genera JScript che, a sua volta, visualizza il titolo dell'applicazione, il nome della 
pagina e i link alle pagine pubblicate. 

TAdapterPageProducer 

TAdapterPageProducer crea schede e tabelle mediante la generazione di HTML e 
JScript. Lo JScript generate chiama gli oggetti adapter per acquisire i valori dei 
campi, parametri dei campi immagine e i parametri delle azioni. 

Modifica e visualizzazione di script 



Per visualizzare l'HTML risulatante dall'esecuzione dello script utilizzare la pagina 
HTML Result. Utilizzare la pagina Preview per visualizzare il risultato in un 
browser. La pagina HTML Script e disponibile se il modulo pagina Web utilizza 
TAdapterPageProducer. La pagina HTML Script visualizza il codice HTML e JScript 
generati dall'oggetto TAdapterPageProducer. Consultare questa vista per vedere come 
scrivere script che costruiscono schede HTML per visualizzare campi dell'adapter ed 
eseguire azioni dell'adapter. 

Inclusione di script in una pagina 



Un modello puo includere script provenienti da un file o da un'altra pagina. Per 
includere script provenieenti da un file, utilizzare la seguente istruzione: 

<!-- # include file="f ilename.html" --> 

Se il modello include script di un'altra pagina, lo script viene valutato dalla pagina 
che effettua l'inclusione. Per includere il contenuto non valutato di pagel, utilizzare 
la seguente istruzione. 

<!-- ftinclude page="pagel" -- > 

Oggetti script 

Gli oggetti script sono oggetti che i comandi dello script possono referenziare. E 
possibile rendere gli oggetti disponibili alio scripting registrando un'interfaccia 
IDispatch verso l'oggetto con il motore di active scripting. I seguenti oggetti sono 
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disponibili per lo scripting: 



Tabella 34.4 Oggetti 
Oggetto script 



script 

Descrizione 



Application Consente l'accesso all'adapter applicazione del modulo Web Application. 

EndUser Consente l'accesso all'adapter utente finale del modulo Web Application. 

Session Consente l'accesso aU'oggetto sessione del modulo Web Application. 

Pages Consente l'accesso alle pagine dell'applicazione. 

Modules Consente l'accesso ai moduli dell'applicazione. 

Page Consente l'accesso alia pagina corrente 

Producer Consente l'accesso al produttore di pagina del modulo pagina Web. 

Response Consente l'accesso a WebResponse. Utilizzare questo oggetto quando non 

si desidera la sostituzione dei marcatori. 

Request Consente l'accesso a WebRequest. 

Adapter objects Tutti i componenti adapter sulla pagina corrente possono essere 

referenziati senza qualifica. Gli adattatori in altri moduli devono essere 
qualificati utilizzando gli oggetti Modules. 



Gli oggetti script sulla pagina corrente, che utilizzano tutti lo stesso adapter, possono 
essere referenziati senza qualifica. Gli oggetti script su altre pagine fanno parte di un 
altro modulo pagina e hanno un oggetto adapter diverso. E possibile accedervi 
anteponendo al riferimento dell'oggetto script il nome dell'oggetto adapter. Ad 
esempio, 

<%= FirstName %> 

visualizza il contenuto della proprieta FirstName dell'adapter della pagina corrente. 
La seguente riga di script visualizza la proprieta FirstName di Adapterl, che e in un 
altro modulo di pagina: 

<%= Adapterl. FirstName %> 

Per una descrizione esaustiva degli oggetti script, vedere l'appendice "Guida di 
riferimento per lo script lto server di WebSnap. 



Indirizzamento di richieste e risposte 



Un motivo per utilizzare WebSnap per lo sviluppo di applicazioni per Web server e 
che componenti WebSnap gestiscono automaticamente le richieste e le risposte 
HTML. Invece di scrivere gestori di evento per i soliti compiti gravosi di 
trasferimento delle pagine, e possibile incentrare i propri sforzi sulla logica di 
gestione e sulla progettazione del server. Nonostante cio, puo essere utile capire in 
che modo le applicazioni WebSnap gestiscono le richieste e le risposte HTML. Questa 
sezione presenta una panoramica di tale processo. 

Prima di gestire qualsiasi richiesta, il modulo Web application inizializza l'oggetto 
(di tipo TWebContext) Web context. L'oggetto Web context, a cui si accede chiamando 
la funzione globale WebContext, fornisce l'accesso globale alle variabili utilizzate dai 
componenti che soddisfano la richiesta. Ad esempio, Web context contiene gli oggetti 
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TWebRequest e TWebResponse per rappresentare il messaggio di richiesta HTTP e la 
risposta che dovrebbero essere restituiti. 

Componenti dispatcher 



I componenti dispatcher nel modulo Web application controllano il flusso 
dell'applicazione. I dispatcher determinano come gestire alcuni tipi di messaggi di 
richiesta HTTP esaminando la richiesta HTTP. 

II componente adapter dispatcher (TAdapterDispatcher) cerca un campo di contenuti o 
un campo query, che identifica un componente adapter action o un componente 
adapter image field. Se l'adapter dispatcher trova un componente, passa controllo a 
quel componente. 

II componente Web dispatcher (TWebDispatcher) gestisce una raccolta di elementi di 
azione (di tipo TWebActionltem) che sanno come gestire alcuni tipi di messaggi di 
richiesta HTTP. II Web dispatcher cerca un elemento di azione che soddisfi la 
richiesta. Se ne trova uno, passa il controllo a quell'elemento di azione. II Web 
dispatcher cerca anche componenti auto-dispatching che possano gestire la richiesta. 

II componente page dispatcher (TPageDispatcher) esamina la proprieta Pathlnfo 
dell'oggetto TWebRequest , cercando il nome di un modulo pagina Web registrato. Se 
il dispatcher trova un nome di modulo pagina Web, passa il controllo a quel modulo. 

Operazioni dell'adapter dispatcher 



II componente adapter dispatcher (TAdapterDispatcher) gestisce automaticamente 
l'inoltro di schede HTML e le richieste di immagini dinamiche, chiamando i 
componenti adapter action e field. 

Utilizzo di componenti adapter per generare contenuti 

Affinche le applicazioni WebSnap eseguano automaticamente le azioni dell'adapter e 
ottengano le immagini dinamiche dai campi dell'adapter, e necessario che il 
contenuto HTML sia costruito correttamente. Se il contenuto HTML non e costruito 
correttamente, la richiesta HTTP risultante non conterra le informazioni di cui 
necessita il dispatcher degli adapter per chiamare i componenti adapter action e 
campo. 

Per ridurre gli errori nella costruzione della pagina HTML, i componenti adapter 
indicano i nomi e i valori degli elementi HTML. I componenti adapter hanno metodi 
che acquisiscono i nomi e i valori di campi nascosti che devono apparire su una 
scheda HTML progettata per aggiornare i campi dell'adapter. Di solito, i produttori 
di pagine utilizzano lo script lato server per acquisire i nomi e i valori dai 
componenti adapter e quindi utilizzano queste informazioni per generare il codice 
HTML. Ad esempio, il seguente script costruisce un elemento <IMG> che referenzia 
il campo di nome Graphic di Adapterl: 

<img src="<l=Adapterl .Graphic . Image. AsHREF%>" alt ="<l=Adapterl .Graphic .DisplayText%>"> 
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Quando l'applicazione web valuta lo script, l'attributo HTML src conterra le 
informazioni necessarie per identificare il campo e tutti i parametri necessari al 
componente campo per acquisire rimmagine. II codice HTML risultante potrebbe 
assomigliare a questo: 

<img src="?_lSpecies No=90090&__id=DM. Adapterl .Graphic" alt=" (GRAPHIC) "> 

Quando il browser manda una richiesta HTTP per acquisire questa immagine 
all'applicazione web, il dispatcher degli adapter sara in grado di determinare che il 
campo Graphic di Adapterl, nel modulo DM, dovrebbe essere chiamato con il 
parametro "Species No=90090". II dispatcher degli adapter chiamera il campo 
Graphic per scrivere una risposta HTTP appropriata. 

II seguente script costruisce un elemento <A> che referenzia l'azione EditRow di 
Adapterl e crea un collegamento ipertestuale a una pagina chiamata Details: 

<a href="<%=Adapterl. EditRow. LmkToPage( "Details", Page. Name) .AsHREF%>">Edit . . .</a> 

II codice HTML risultante potrebbe assomigliare a questo: 

<a href="?&_lSpecies No=90310&__sp=Edit&__fp=Grid&__id=DM. Adapterl. EditRow" >Edit . . .</a> 

L'utente finale fa clic su questo collegamento ipertestuale e il browser invia una 
richiesta HTTP. II dispatcher degli adapter e in grado di determinare che l'azione 
EditRow di Adapterl, nel modulo DM, dovrebbe essere chiamata con il parametro 
Species No=903010. II dispatcher degli adapter visualizza la pagina Edit se l'azione 
va a buon fine e visualizza la pagina Grid se l'esecuzione dell'azione non riesce. 
Quindi chiama l'azione EditRow per individuare la riga da modificare e viene 
chiamata la pagina di nome Edit per generare una risposta HTTP. La Figura 34.12 
mostra come sono utilizzati i componenti adapter per generare dei contenuti. 

Figura 34.12 Generazione del flusso dei contenuti 
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Ricezione di richieste dell'adapter e generazione delle risposte 

Quando il dispatcher degli adattatori riceve una richiesta client, il dispatcher degli 
adattatori crea oggetti adapter request e adapter response per conservare le 
informazioni relative a quella richiesta HTTP. Gli oggetti oggetti adapter request e 
adapter response sono memorizzati nel Web context per consentire l'accesso durante 
l'elaborazione della richiesta. 
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II dispatcher degli adapter crea due tipi di oggetti adapter request: action e image. 
Crea l'oggetto richiesta di azione quando esegue un'azione di adapter. Crea l'oggetto 
richiesta di immagine quando ricerca un'immagine da un campo dell'adapter. 

L'oggetto adapter response e utilizzato dal componente adapter per indicare la 
risposta a una richiesta adapter action o adapter image. Esistono due tipi di oggetti 
adapter response, action e image. 

Richieste di azioni 

Gli oggetti di richiesta di azioni sono responsabili di suddividere la richiesta HTTP in 
informazioni necessarie per eseguire un'azione dell'adapter. I tipi di informazioni 
necessarie per l'esecuzione di un'azione dell'adapter possono includere le seguenti 
informazioni di richiesta: 



Tabella 34.5 Informazioni di richiesta presenti nelle richieste di azioni 

Descrizione 



Informazione della 
richiesta 



Nome componente 
Adapter mode 

Success page 
Failure page 

Action request parameters 
Adapter field values 

Record keys 



Identifica il componente adapter action. 

Definisce una modalita. Ad esempio, TDataSetAdapter supporta le 
modalita Edit, Insert e Browse. Un adapter action pud comportarsi in 
diversi modi a seconda della modalita. 

Identifica la pagina visualizzata dopo l'esecuzione con successo 
dell'azione. 

Identifica la pagina visualizzata nel caso si verifiche un errore 
durante l'esecuzione dell'azione. 

Identifica i parametri necessari all'adapter action. Ad esempio, 
l'azione Apply di TdataSet Adapter includera i valori chiave che che 
identificano il record da aggiornare. 

Specifica valori dei campi dell'adapter passati nella richiesta HTTP 
quando si trasmette una scheda HTML. Un valore del campo puo 
includere nuovi valori immessi dall'utente finale, i valori originali 
del campo dell'adapter e i file caricati. 

Specifica le chiavi che identificano in modo univoco ogni record. 



Generazione delle risposte di azione 

Gli oggetti action response generano una risposta HTTP per conto di un componente 
adapter action. L'adapter action indica il tipo di risposta impostando proprieta 
all'interno dell'oggetto o chiamando metodi nell'oggetto action response. Le 
proprieta includono: 

• RedirectOptions — Le opzioni di reindirizzamento indicano se eseguire un 
reindirizzamento HTTP invece di restituire dei contenuti HTML. 

• ExecutionStatus — L'impostazione dello stato a Success fa in modo che Paction 
response predefinita sia il contenuto della pagina Success identificata nell'Action 
Request. 

I metodi di action response includono: 

• RespondWithPage — L'adapter action chiama questo metodo quando un particolare 
modulo pagina Web dovrebbe generare la risposta. 
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• RespondWithComponent — L'adapter action chiama questo metodo quando la 
risposta dovrebbe venire dal modulo pagina Web che contiene questo 
componente. 

• RespondWithURL — L'adapter action chiama questo metodo quando la risposta e 
un reindirizzamento all'URL specificato. 

Quando risponde con una pagina, l'oggetto action response tenta di utilizzare il 
dispatcher delle pagine per generare contenuti della pagina. Se non trova il 
dispatcher delle pagine, chiama direttamente il modulo pagina Web. 

La Figura 34.15 illustra il modo in cui gli oggetti action request and action response 
gestiscono una richiesta. 

Figura 34.13 Action request e response 
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Richiesta di immagine 

informazioni richieste dal campo immagine dell'adapter per generare un'immagine. 
I tipi di informazioni rappresentate da Image Request includono: 

• Component name - Identifica il componente campo dell'adapter. 

• Image request parameters - Identifica i parametri necessari per l'adapter image. 
Ad esempio, all'oggetto TDataSetAdapterlmageField sono necessari dei valori 
chiave per identificare il record che contiene l'immagine. 

Risposta di immagine 

L'oggetto image response contiene l'oggetto TWebResponse. I campi dell'adapter 
rispondono a una richiesta dell'adapter scrivendo un'immagine nell'oggetto Web 
response. 

La Figura 34.14 illustra illustra il modo in cui i campi immagine dell'adapter 
rispondono a una richiesta. 
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Figura 34.14 Risposta di immagine a una richiesta 
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Indirizzamento degli elementi di azione 



Quando risponde a una richiesta, il Web dispatcher ( TWebDispatcher) ricerca nel suo 
elenco di elementi di azione quello che: 

• corrisponde alia parte Pathlnfo dell'URL di destinazione del messaggio di 
richiesta, e 

• e in grado di fornire il servizio specificato come il metodo del messaggio di 
richiesta. 

L'operazione viene svolta confrontando le proprieta Pathlnfo e MethodType 
dell'oggetto TWebRequest con le proprieta aventi lo stesso nome sull'elemento di 
azione. 

Quando il dispatcher trova l'elemento di azione appropriate provoca l'innesco di 
quell'elemento di azione. Quando l'elemento di azione viene innescato, fa una delle 
seguenti cose: 

• Compila il contenuto della risposta e invia la risposta o segnala che la richiesta e 
stata gestita completamente. 

• Aggiunge alia risposta e quindi permette ad altri elementi di azione di completare 
il lavoro. 

• Rimanda la richiesta ad altri elementi di azione. 

Dopo che il dispatcher ha controllato tutti i suoi elementi di azione, se il messaggio 
non e stato gestito correttamente, il dispatcher controlla la presenza di componenti di 
auto-dispatching registrati appositamente che non utilizzano elementi di azione. 
(Questi componenti sono specif ici per le applicazioni database multi-tiered). Se il 
messaggio di richiesta non viene ancora gestito completamente, il dispatcher chiama 
l'elemento di azione predefinito. Non e necessario che l'URL di destinazione o il 
metodo della richiesta corrispondano all'elemento di azione predefinito. 
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Operazione del dispatcher di pagine 



Quando il dispatcher di pagine riceve una richiesta del client, determina il nome 
della pagina controllando la parte Pathlnfo del messaggio di richiesta dell'URL di 
destinazione. Se la parte Pathlnfo non e vuota, il dispatcher di pagine utilizza come 
nome della pagina la parola finale di Pathlnfo. Se la parte Pathlnfo e vuota, il 
dispatcher di pagine cerca di determinare un nome di pagina predefinito. 

Se la proprieta DefaultPage del dispatcher di pagine contiene un nome di pagina, il 
dispatcher di pagine utilizza questo nome come nome di pagina predefinito. Se la 
proprieta DefaultPage e vuota e il modulo Web application e un modulo pagina, il 
dispatcher di pagine utilizza il nome del modulo Web application come nome di 
pagina predefinito. 

Se il nome della pagina non e vuoto, il dispatcher di pagine cerca un modulo pagina 
Web con un nome corrispondente. Se trova un modulo pagina Web, chiama quel 
modulo per generare una risposta. Se il nome della pagina e vuoto o se il dispatcher 
di pagine non trova un modulo pagina Web, il dispatcher di pagine solleva 
un'eccezione. 

La Figura 34.15 mostra come il dispatcher delle pagine risponde a una richiesta. 
Figura 34.15 Indirizzamento di una pagina 
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Operazioni con documenti XML 

XML (Extensible Markup Language) e un linguaggio di markup per la descrizione di 
dati strutturati. E simile a HTML, tranne che i marcatori descrivono la struttura delle 
informazioni invece delle caratteristiche di visualizzazione. I documenti XML 
rappresentano un modo semplice, basato su testo, per memorizzare informazioni in 
modo da semplificarne la ricerca o la modifica. Essi sono utilizzati spesso come 
formato standard e trasportabile per dati in applicazioni Web, in comunicazioni 
business-to-business e cosi via. 

I documenti XML forniscono una vista gerarchica di un corpo di dati. I marcatori nel 
documento XML descrivono il ruolo o il significato di ogni dato, come si vede nel 
seguente documento, che descrive una raccolta di titoli azionari: 

<?xml version=' 1. 0" encoding=UTF-8 standalone="no" ?> 
<!D0CTYPE StockHoldings SYSTEM "sth.dtd"> 
<StockHoldings> 

<Stock exchange= " NASDAQ " > 
<name>Borland</name> 
<price>15 .375</price> 
<symbo 1>B0RL< / symbol> 
<shares>100</shares> 
</Stock> 

<Stock exchange="NYSE"> 

<name>Pf izer</name> 

<price>42 . 75</price> 

<symbol>PFE</symbol> 

<shares type= "preferred 11 >25</shares> 
</Stock> 
</StockHoldings> 

Questo esempio illustra molti elementi tipici in un documento XML. La prima riga e 
un'istruzione di elaborazione che viene chiamata dichiarazione di XML. La 
dichiarazione XML e facoltativa ma si dovrebbe includerla in quanto fornisce 
informazioni utili sul documento. In questo esempio, la dichiarazione XML dice che 
il documento e conforme alia versione 1.0 delle specif iche XML, che utilizza la 
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codifica UTF-8 e che si basa su un file esterno per la dichiarazione del tipo di 
documento (DTD)). 

La seconda riga, che inizia con il marcatore <!DOCType>, e una dichiarazione del 
tipo di documento. La dichiarazione del tipo di documento (DTD) e il modo in cui 
XML definisce la struttura del documento. Essa impone regole sintattiche relative 
agli elementi (marcatori) contenuto nel documento. II DTD in questo esempio 
referenzia un altro file (sth.dtd). In questo caso, la struttura e definita in un file 
esterno, invece che aH'intemo dello stesso documento XML. Altri tipi di file che 
descrivono la struttura di un documento XML includono XDR (Reduced XML Data) 
e XDR (XML schema). 

Le restanti righe sono organizzate gerarchicamente con un singolo nodo radice (il 
marcatore <StockHoldings>). Ogni nodo in questa gerarchia contiene o un insieme di 
nodi figlio, o un valore di testo. Alcuni marcatori (i marcatori <Stock> e <shares>) 
includono attributi, che sono coppie Name=Value che forniscono dettagli su come 
interpretare il marcatore. 

Benche sia possibile operare direttamente con il testo in un documento XML, di solito 
le applicazioni utilizzano particolari strumenti aggiuntivi per l'analisi sintattica e la 
modifica dei dati. W3C definisce un insieme di interfacce standard per rappresentare 
un documento analizzato XML di nome DOM (Document Object Model). Molti 
fornitori forniscono parser XML che implementano le interfacce DOM per 
semplificare l'interprezione e la modifica di documenti XML. 

C++Builder fornisce molti strumenti aggiuntivi per operare con i documenti XML. 
Questi strumenti utilizzano un parser DOM, fornito da un altro produttore, e 
facilitano notevolmente le operazioni sui documenti XML. Questo capitolo descrive 
questi strumenti. 

Oltre agli strumenti descritti in questo capitolo, C++Builder dispone di strumenti e 
componenti per la conversione di documenti XML in pacchetti dati che si integrano 
nell'architettura database di C++Builder. Per maggiori informazioni sugli strumenti 
per integrare i documenti XML nelle applicazioni database, consultare il Capitolo 30, 
"Uso di XML nelle applicazioni database". 
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II Document Object Model (DOM) e un insieme di interfacce standard per 
rappresentare un documento XML analizzato. Per impostazione predefinita, nel 
prodotto e inclusa una copia dell'implementazione DOM di Microsoft. Inoltre, 
include un meccanismo di registrazione che permette di integrare nel framework 
XML ulteriori implementazioni DOM di altri produttori. 

La unit XMLDOM include le dichiarazioni per tutte le interfacce DOM definite nelle 
specifiche W3C XML DOM level 2. Ogni produttore DOM fornisce una propria 
implementazione per queste interfacce. 

• Per utilizzare l'implementazione Microsoft, includere nel file sorgente l'header 
della unit MSXMLDOM. Poiche l'implementazione Microsoft e basata su COM, e 
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inoltre necessario registrare la libreria msxml.dll come server COM, qualora non 
lo fosse gia. Per registrare questa DLL e possibile utilizzare Regsvr32.exe. 

• Per utilizzare un'altra implementazione DOM, e necessario creare una unit che 
definisca un derivato della classe TDOMVendor. Nella classe discendente, e 
necessario ridefinire due metodi: il metodo Description, che restituisce una stringa 
che identifica il fornitore e il metodo DOMImplementation, che restituisce 
l'interfaccia di alto livello (IDOMImplementation). Si dovrebbe registrare questo 
fornitore chiamando la procedura globale RegisterDOMVendor. E possibile 
annullare la registrazione del fornitore chiamando la procedura globale 
UnRegisterDOMVendor. Una volta che si e registrato il nuovo DOMVendor, 
l'applicazione ha accesso all'implementazione DOM sottostante finche non si 
elimina la registrazione del fornitore. 

Alcuni produttori forniscono estensioni alle interfacce DOM standard. Per consentire 
l'utilizzo di queste estensioni, la unit XMLDOM definisce anche un'interfaccia 
IDOMNodeEx. IDOMNodeEx e un discendente della IDOMNode standard che include 
la piu utile di queste estensioni. 

E possibile operare direttamente con interfacce DOM per analizzare e modificare 
documenti XML. E sufficiente chiamare la funzione GetDOM per ottenere 
un'interfaccia IDOMImplementation, che e possibile utilizzare come punto di 
partenza. 

Per una descrizione dettagliata delle interfacce DOM, vedere le dichiarazioni nello 
header della unit XMLDOM, la documentazione fornita dal produttore DOM o le 
specifiche fornite sul sito Web di W3C (www.w3.org). 

Potrebbe pero risultare piu conveniente utilizzare le classi XML invece di operare 
direttamente con le interfacce DOM. Queste classi sono descritte di seguito. 
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La VCL (o la CLX) definisce molte classi e interfacce per operare con i documenti 
XML. Questi semplificano il processo di caricamento, modifica e salvataggio dei 
documenti XML. 

Utilizzo di TXMLDocument 



II punto di partenza per operare con un documento XML e il componente 
TXMLDocument. I seguenti punti descrivono come utilizzare TXMLDocument per 
operare direttamente con un documento XML: 

1 Aggiungere un componente TXMLDocument alia scheda o al modulo dati. 
TXMLDocument e presente sulla pagina Internet della Component palette. 

2 Impostare la proprieta DOMVendor per specificare l'implementazione DOM che si 
vuole venga utilizzata dal componente per l'analisi sintattica e la modifica di un 
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documento XML. L' Object Inspector elenca tutti i produttori DOM attualmente 
registrati. Per informazioni sulle implementazioni DOM, consultare "Utilizzo del 
Document Object Model" a pagina 35-2. 

3 A seconda dell'implementazione, si potrebbe voler impostare la proprieta 
ParseOptions in modo da configurare in che modo l'implementazione DOM 
sottostante analizza il documento XML. 

4 Se si sta operando con un documento XML esistente, specificare il documento: 

• Se il documento XML e memorizzato in un file, impostare la proprieta FileName 
al nome di quel file. 

• Utilizzando invece la proprieta XML e possibile specificare il documento XML 
come una stringa. 

5 Impostate la proprieta Active a true. 

Una volta che si ha un oggetto TXMLDocument attivo, e possibile esaminare la 
gerarchia dei suoi nodi oltre che leggere o impostare i rispettivi valori. II nodo radice 
di questa gerarchia e disponibile come proprieta DocumentElement. 

Operazioni con i nodi XML 



Una volta che un documento XML e stato analizzato da un'implementazione DOM, i 
dati che esso rappresenta sono disponibili sotto forma di gerarchia di nodi. Ogni 
nodo corrisponde a un elemento marcato nel documento. Ad esempio, dato il 
seguente XML: 

<?xml version="1.0" encoding="UTF-8" standalone="no" ?> 
<!D0CTYPE StockHoldings SYSTEM "sth.dtd"> 
<StockHoldings> 

<Stock exchange= " NASDAQ " > 
<name>Borland</name> 
<price>15 . 375</price> 
< symbo 1 >B0RL< / symbol > 
<shares>100</shares> 
</Stock> 

<Stock exchange="NYSE"> 

<name>Pf izer</name> 

<price>42 . 75</price> 

<symbol>PFE</symbol> 

<shares type= "preferred 11 >25</shares> 
</Stock> 
</StockHoldings> 

TXMLDocument genererebbe una gerarchia di nodi di questo tipo: La radice della 
gerarchia sarebbe il nodo StockHoldings. StockHoldings avrebbe due nodi figlio, che 
corrispondono alle due marcatori Stock. Ognuno di questi due nodi figlio avrebbe 
quattro nodi figlio propri (name, price, symbol e shares). Quei quattro nodi figlio 
agirebbero come nodi foglia. II testo che essi contengono verrebbe visualizzato come 
il valore di ognuno dei nodi foglia. 
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Questa divisione in nodi e leggermente diversa dal modo in cui un'implementazione 
DOM genera i nodi per un documento XML. In particolare, un parser DOM tratta 
tutti gli elementi marcati come nodi interni. Per i valori dei name, price, symbol e shares 
verrebbero creati dei nodi aggiuntivi (di tipo nodo di testo). Questi nodi di testo 
sarebbero quindi visualizzati come figli dei nodi name, price, symbol e shares. 

Ad ogni nodo si accede attraverso un'interfaccia IXMLNode a partire dal nodo radice, 
che e il valore della proprieta DocumentElement. 

Operazioni con il valore di un nodo 

Data un'interfaccia IXMLNode, e possibile controllare se rappresenta un nodo interno 
o un nodo foglia controllando la proprieta IsTextElement. 

• Se rappresenta un nodo foglia, e possibile leggerne o impostarne il valore 
utilizzando la proprieta Text. 

• Se rappresenta un nodo interno, e possibile accedere ai suoi nodi figlio utilizzando 
la proprieta ChildNodes. 

Cosi, ad esempio, utilizzando il documento XML visto in precedeza, e possibile 
leggere il prezzo dell'azione Borland nel seguente modo: 

_di_IXMLNode BorlandStock = XMLDocumentl->DocumentElement->ChildNodes->GetNode(0) ; 
AnsiString Price = BorlandStock->ChildNodes->Nodes [WideString ( "price" )] ->Text ; 

Operazioni con gli attributi di un nodo 

Se il nodo include eventuali attributi, e possibile operare su di essi utilizzando la 
proprieta Attributes. E possibile leggere o modificare il valore di un attributo 
specificando il nome di un attributo esistente. Quando si imposta la proprieta 
Attributes e possibile aggiungere nuovi attributi specificando un nuovo nome di 
attributo: 

_di_IXMLNode BorlandStock = XMLDocumentl->DocumentElement->ChildNodes->GetNode(0) ; 
BorlandStock- >ChildNodes->Nodes [Widest ring ( "shares" ) ] ->At tributes [WideString ( "type" ) ] = 
"common" ; 

Aggiunta e cancellazione di nodi figlio 

E possibile aggiungere nodi figlio utilizzando il metodo AddChild. AddChild crea 
nuovi nodi che corrispondono a elementi contrassegnati nel documento XML. Tali 
nodi sono chiamati nodi elemento. 

Per creare un nuovo nodo elemento, specificare il nome che apparira nel nuovo 
marcatore e, volendo, la posizione in cui dovrebbe essere visualizzato il nuovo nodo. 
Ad esempio, il seguente codice aggiunge un nuovo titolo azionario al documento 
visto in precedenza: 

_di_IXMLNode NewStock = XMLDocumentl->Document Element ->AddChi Id (WideString! "stock" )) ; 

NewStock->Attributes [WideString ("exchange")] = "NASDAQ"; 

_di_IXMLNode ValueNode = NewStock->AddChild(WideString("name") ) ; 

ValueNode->Text = WideString ("Cisco Systems"); 

ValueNode = NewStock->AddChild (WideString) "price" )) ; 

ValueNode->Text = WideString! "62 .375" ) ; 

ValueNode = NewStock->AddChild(WideString("symbol") ) ; 
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ValueNode->Text = WideString("CSCO"); 

ValueNode = NewStock->AddChild(WideString("shares") ) ; 

ValueNode->Text = WideString("25") ; 

Una versione ridefinita di AddChild permette di specificare il namespace URI in cui e 
definito il nome del marcatore. 

E possibile cancellare i nodi figlio utilizzando i metodi della proprieta ChildNodes. 
ChildNodes e un'interfaccia IXMLNodeList, che gestisce i figli di un nodo. E possibile 
utilizzare il metodo Delete per cancellare un singolo nodo figlio identificato in base 
alia posizione o al nome. Ad esempio, il seguente codice cancella l'ultimo titolo 
azionario nel documento visto in precedenza: 

_di_IXMLNode StockList = XMLDocumentl->DocumentElement; 
StockList->ChildNodes->Delete(StockList->ChildNodes->Count - 1) ; 

Astrazione di documenti XML con Data Binding wizard 



Benche sia possibile operare con un documento XML utilizzando solo il componente 
TXMLDocument e l'interfaccia IXMLNode, che fa emergere i nodi in quel documento, 
o, addirittura, operare esclusivamente con le interfacce DOM (evitando anche 
TXMLDocument), mediante l'utilizzo di XML Data Binding wizard e possibile 
scrivere del codice molto piu semplice e piu facilmente leggibile. 

Data Binding wizard prende uno schema XML o un file di dati e genera un set di 
interfacce che ne tracciano una mappa. (Un'interfaccia e una classe che contiene solo 
membri pure virtual). Si supponga di avere, ad esempio, una serie di dati XML simile 
alia seguente: 

<customer id=l> 

<name>Mark</name> 

<phone>(831) 431-1000</phone> 
</customer> 

Data Binding wizard genera la seguente interfaccia (oltre a una classe per 
implementarla): 

..interface INTERFACE.UUID ( " { F3 72 9 1 05 -3DD0 - 12 3 4 - 8 OeO -2 2 A04FE7B45 1 } " ) ICustomer : 
public IXMLNode 

{ 

public : 

virtual int fastcall Getid(void) = ; 

virtual DOMString fastcall Getname (void) = ; 

virtual DOMString fastcall Getphone (void) = ; 

virtual void __fastcall Setid(int Value) = ; 
virtual void ..fastcall Setname (DOMString Value) = ; 
virtual void __fastcall Setphone (DOMString Value) = ; 
..property int id = {read=Getid, write=Setid} ; 
..property DOMString name = {read=Getname, write=Setname} ; 
..property DOMString phone = {read=Getphone, write=Setphone} ; 

}; 

Ogni nodo figlio viene fatto corrispondere a una proprieta, il cui nome corrisponde al 
nome del marcatore del nodo figlio e il cui valore e l'interfaccia del nodo figlio (nel 
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caso il nodo figlio sia un nodo interno) o con il valore del nodo figlio (nel caso di nodi 
foglia). Anche ogni attributo di nodo viene fatto corrispondere con una proprieta, in 
cui il nome della proprieta e il nome dell'attributo e il valore della proprieta e il 
valore dell'attributo. 

Oltre alia creazione di interfacce (e delle classi di implementazione discendenti) per 
ogni elemento contrassegnato incluso nel documento XML, il wizard crea una 
funzione globale per ottenere l'interfaccia verso il nodo radice. Ad esempio, se lo 
XML di cui sopra provenisse da un documento al cui nodo radice era associato il 
marcatore <Customers>, Data Binding wizard creerebbe le seguente routine globali: 



extern 


PACKAGE 


_di. 


JCustomers 


__fastcall 


GetCustomers (TXMLDocument *XMLDoc) ; 


extern 


PACKAGE 


_di. 


JCustomers 


__fastcall 


GetCustomers Ldi_IXMLDocument XMLDoc) ; 


extern 


PACKAGE 


_di. 


JCustomers 


__fastcall 


LoadCustomers (const WideString FileName 


extern 


PACKAGE 


_di. 


JCustomers 


__fastcall 


NewCustomers (void) ; 



La funzione Get... accetta il wrapper dell'interfaccia di un'istanza TXMLDocument (o 
di un puntatore a quell'istanza di TXMLDocument). La funzione Load... crea 
dinamicamente un'istanza di TXMLDocument e carica il file XML specificato come 
suo valore prima di restituire un puntatore all'interfaccia. La funzione New... crea 
una nuova istanza (vuota) di TXMLDocument e restituisce l'interfaccia al nodo radice. 

L'utilizzo delle interfacce generate semplifica il codice, perche riflettono la struttura 
del documento XML in modo piu diretto. Ad esempio, invece di scrivere del codice 
simile al seguente: 

_diJEXMLNode Custlntf = XMLDocumentl->Document Element; 

CustName = Custlntf->ChildNodes->Nodes->GetNode(0) ->ChildNodes->Nodes [WideString! "name" ) ] - 
>Value; 

II codice sarebbe invece: 

_di_ICustomers Custlntf = GetCustomers (XMLDocumentl) ; 
CustName = CustIntf->Nodes->GetNode(0)->Name; 

Si noti che le interfacce generate da Data Binding wizard discendono tutte da 
IXMLNode. Cio significa che e sempre possibile aggiungere e cancellare i nodi figlio 
secondo le stesse modalita di quando non si utilizza Data Binding wizard. (Vedere 
"Aggiunta e cancellazione di nodi figlio" a pagina 35-5). Inoltre, quando i nodi figlio 
rappresentano elementi ripetitivi (quando tutti i figli di un nodo sono dello stesso 
tipo), al nodo genitore vengono assegnati due metodi, Add e Insert, per l'aggiunta di 
ulteriori ripetizioni. Questi metodi sono piu semplici rispetto all'utilizzo di AddChild, 
perche non e necessario specificare il tipo di nodo da creare. 

Utilizzo di XML Data Binding wizard 



Per utilizzare Data Binding wizard, 

1 Scegliere File I New I Other e selezionare l'icona con l'etichetta XML Data Binding 
nella zona inferiore della pagina New. 

2 Viene visualizzato XML Data Binding wizard. 
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3 Sulla prima pagina del wizard specificare il documento o lo schema XML per cui si 
desidera generare interfacce. Questo puo essere un documento XML di esempio, 
un file Document Type Definition (.did), un file Reduced XML Data (.xdr) o un file 
di schema XML (.xsd. 

4 Fare clic sul pulsante Options per specificare le strategie per l'assegnazione dei 
nomi che si vuole vengano utilizzate dal wizard durante la generazione delle 
interfacce e delle classi di implementazione e la mappatura predefinita dei tipi 
definiti nello schema in tipi di dati nativi. 

5 Passare alia seconda pagina del wizard. Questa pagina permette di fornire 
informazioni dettagliate su ogni tipo di nodo nel documento o nello schema. Alia 
sinistra c'e una vista ad albero che visualizza che tutto i tipi di nodo presenti nel 
documento. Per nodi complessi (nodi che hanno figli), la vista albero puo essere 
estesa in modo da visualizzare gli elementi figlio. Quando si seleziona un nodo 
nella vista ad albero, il lato destro della finestra di dialogo visualizza le 
informazioni su quel nodo e permette di specificare come si desidera che il wizard 
tratti quel nodo. 

• II controllo Source Name visualizza il nome del tipo di nodo nello schema XML. 

• II controllo Source Datatype visualizza il tipo del valore del nodo, come 
specificato nello schema XML. 

• II controllo Documentation permette di aggiungere commenti alio schema per 
descrivere l'utilizzo o lo scopo del nodo. 

• Se il wizard genera del codice per il nodo selezionato (cioe, se e un tipo 
complesso per il quale il wizard genera un'interfaccia e una classe di 
implementazione oppure se e uno degli elementi figlio di un tipo complesso per 
il quale il wizard genera una proprieta sull'interfaccia del tipo complesso), e 
possibile utilizzare la casella di controllo Generate Binding per specificare se si 
desidera che il wizard generi codice per il nodo. Se si deseleziona Generate 
Binding, il wizard non genera l'interfaccia o la classe di implementazione per 
un tipo complesso oppure non crea una proprieta nell'interfaccia genitore di un 
elemento o di un attributo figlio. 

• La sezione Binding Options permette di influire sul codice generato dal wizard 
per l'elemento selezionato. Per qualsiasi nodo, e possibile specificare l'Identifier 
Name (il nome dell'interfaccia o della proprieta generata).Inoltre, per le 
interfacce, e necessario indicare quale rappresenta il nodo radice del 
documento. Per nodi che rappresentano proprieta, e possibile specificare il tipo 
della proprieta e, se la proprieta non e un'interfaccia, se e una proprieta a sola 
lettura. 

6 Una volta specificato quale codice si desidera che il wizard generi per ogni nodo, 
passare alia terza pagina. Questa pagina permette di scegliere alcune opzioni 
globali relative a come il wizard genera il codice, permette di vedere in anteprima 
il codice che sara generato e permette di dire al wizard come salvare le scelte fatte 
per un successivo utilizzo. 

• Per vedere in anteprima il codice generato dal wizard, selezionare 
un'interfaccia nella lista Binding Summary e visualizzare la definizione di 
interfaccia risultante nel controllo Code Preview. 
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• Utilizzare Data Binding Settings per indicare come il wizard dovrebbe salvare 
le scelte. E possibile memorizzare le impostazioni come annotazioni in un file 
di schema, associato al documento (il file di schema specificato nella prima 
pagina della finestra di dialogo) oppure e possibile dare un nome a un file di 
schema indipendente, utilizzato solo dal wizard. 

7 Appena si fa clic su Finish, Data Binding wizard genera una nuova unit che 

definisce le interfacce e le classi di implementazione per tutti i tipi di nodo presenti 
nel documento XML. Inoltre, crea una funzione globale che prende un oggetto 
TXMLDocument e restituisce l'interfaccia per il nodo radice della gerarchia dati. 

Utilizzo del codice generate da XML Data Binding wizard 



Una volta che il wizard ha generato un insieme di interfacce e di classi di 
implementazione, e possibile utilizzarle per operare con documenti XML che 
corrispondono alia struttura del documento o dello schema fornito al wizard. 
Esattamente come quando si utilizzano solo i componenti XML nativi, il punto di 
partenza e il componente TXMLDocument presente sulla pagina Internet della 
Component palette. 

Per operare con un documento XML, fare quanto segue: 

1 Ottenere un'interfaccia per il nodo radice del documento XML. E possibile farlo in 
tre modi: 

• Collocare un componente TXMLDocument sulla scheda o nel modulo dati. 
Collegare il componente TXMLDocument a un documento XML impostando la 
proprieta FileName. (Come metodo alternativo, e possibile utilizzare una stringa 
XML impostando la proprieta XML in esecuzione). Poi, nel codice, chiamare la 
funzione globale creata dal wizard per ottenere un'interfaccia per il nodo radice 
del documento XML. Ad esempio, se l'elemento radice del documento XML era 
il marcatore <StockList>, per impostazione predefinita, il wizard genera una 
funzione GetStockListType, che restituisce un'interfaccia IStockListfype: 

XMLDocumentl->FileName := "Stocks .xml" ; 

_di_IStockListType StockList = GetStockListType (XMLDocumentl) ; 

• Chiamare la funzione generata Load... per creare e collegare l'istanza di 
TXMLDocument e ottenere la sua interfaccia in un solo passaggio. Ad esempio, 
utilizzando lo stesso documento XML descritto in precedenza: 

_di_IStockListType StockList = LoadStockListType ( "Stocks .xml" ) ; 

• Chiamare la funzione New... generata per creare l'istanza di TXMLDocument di 
un documento vuoto quando si vogliono creare tutti i dati nell'applicazione: 

_di_IStockListType StockList = NewStockListType ( ) ; 

2 Questa interfaccia ha proprieta che corrispondono ai sottonodi dell'elemento 
radice del documento, oltre a proprieta che corrispondono agli attributi di 
quell'elemento radice. E possibile utilizzare queste proprieta per percorrere la 
gerarchia del documento XML, modificare i dati nel documento, e cosi via. 
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3 Per salvare tutte le modifiche apportate utilizzando le interfacce generate dal 
wizard, chiamare il metodo SaveToFile del componente TXMLDocument o leggerne 
la proprieta XML. 

Se si imposta la proprieta Options dell'oggetto TXMLDocument in modo da includere 
doAutoSave non e necessario chiamare esplicitamente il metodo SaveToFile. 
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Utilizzo dei Web Services 



I Web Services sono applicazioni modulari indipendenti che possono essere 
pubblicate e richiamate da Internet. I Web Services mettono a disposizione interfacce 
ben definite che descrivono i servizi forniti. A differenza delle applicazioni per Web 
server che generano pagine web per i browser client, le applicazioni Web Services 
non sono progettate per l'interazione diretta con l'utente. Ad esse invece si accede 
mediante il codice dalle applicazioni client. 

I Web Services sono progettati per consentire un accoppiamento flessibile tra client e 
server. Cio significa che le implementazioni server non chiedono che i client 
utilizzino una piattaforma o un linguaggio di programmazione specifici. Oltre a 
definire le interfacce in un modo indipendente dal linguaggio, essi sono progettati 
per consentire anche piu meccanismi di comunicazione. 

II supporto di C++Builder per i Web Services e stato concepito per funzionare 
utilizzando SOAP (Simple Object Access Protocol). SOAP e un protocollo standard 
leggero per lo scambio di informazioni in un ambiente decentrato e distribuito. Esso 
utilizza XML per codificare le chiamate a procedura remote e, come protocollo di 
comunicazione, di solito utilizza HTTP. Per ulteriori informazioni su SOAP, vedere 
le specifiche SOAP disponibili all'indirizzo 

http://www.w3 .org/TR/ SOAP/ 

Benche i componenti che supportano i Web Services siano stati concepiti per 
utilizzare SOAP e HTTP, il framework e sufficientemente generico da poter essere 
ampliato in modo da utilizzare altri protocolli di codifica e di comunicazione. 

Oltre a consentire la costruzione di applicazioni Web Service basate su SOAP 
(server), C++Builder fornisce il supporto per i client dei Web Services che utilizzano 
una codifica SOAP o uno stile Document Literal. Lo stile Document Literal e 
utilizzato nei Web Services .Net. 

I componenti che supportano i Web Services sono disponibili sia in Windows che in 
Linux, e pertanto e possibile utilizzarli come elementi base per applicazioni 
distribute multipiattaforma. Non occorre installare alcun particolare software client 
runtime, come quando si distribuiscono le applicazioni che utilizzano CORBA. 
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Poiche questa tecnologia si basa sui messaggi HTTP, presenta il vantaggio che e 
ampiamente disponibile su una vasta gamma di macchine. II supporto per i Web 
Services si fonda sull'architettura di applicazioni per Web server (Web Broker). 

Le applicazioni Web Service pubblicano mediante un documento WSDL (Web 
Service Definition Language) informazioni sulle interfacce disponibili e su come 
chiamarle. Sul lato server, l'applicazione puo pubblicare un documento WSDL che 
descrive il Web Service. Sul lato client, un wizard o programma di utilita a riga di 
comando puo importare un documento WSDL pubblicato, fornendo le definizioni 
delle interfacce e le informazioni di connessione necessarie. Se gia si possiede un 
documento WSDL che descrive il servizio Web che si desidera implementare, e 
possibile generare il codice lato server anche quando si importa il documento WSDL. 

Le interfacce richiamabili 



I server che supportano i Web Services sono costruiti utilizzando interfacce 
richiamabili. Le interfacce richiamabili sono classi pure virtual (classi che includono 
solo metodi pure virtual) che vengono compilate in modo da includere informazioni 
di tipo in esecuzione (RTTI). Sul server, queste RTTI vengono utilizzate durante 
l'interpretazione delle chiamate ai metodo in arrivo dai client in modo che possano 
essere smistate correttamente. Sui client, queste RTTI vengono utilizzate per generare 
dinamicamente una tabella dei metodi per ef fettuare chiamate ai metodi 
dell'interfaccia. 

Per creare un'interfaccia richiamabile, e necessario dichiarare la classe dell'interfaccia 
utilizzando la parola chiave _declspec , utilizzando il modificatore delphirtti. Anche il 
discendente di qualsiasi interfaccia richiamabile e a sua volta richiamabile. Tuttavia, 
se un'interfaccia richiamabile discende da un'altra classe di interfaccia che non e 
richiamabile, il Web Service puo solo utilizzare i metodi definiti nell'interfaccia 
richiamabile e nei suoi discendenti. I metodi ereditati da antenati non richiamabili 
non vengono compilati con le informazioni di tipo e non possono essere cosi 
utilizzati come parte del Web Service. 

Per informazioni sulle classi di interfaccia in C++Builder, vedere "Eredita e 
interfacce" a pagina 13-2. 

II file header sysmac.h definisce un'interfaccia richiamabile di base, Ilnvokable, da cui 
e possibile derivare qualsiasi interfaccia esposta ai client da un server Web Service. 
Ilnvokable e identica all'interfaccia di base (Ilnterface), tranne per il fatto che e 
compilata utilizzando l'opzione _declspec (delphirtti) in modo che essa e tutti i suoi 
discendenti includano le RTTI. 

Ad esempio, il seguente codice definisce un'interfaccia richiamabile che contiene due 
metodi per codificare e decodificare valori numerici: 

..interface INTERFACE_UUID("{C527B88F-3F8E-1134-80eO-01A04F57B270}") IEncodeDecode : 
public Ilnvokable 

{ 

public : 

virtual double stdcall EncodeValuefint Value) = ; 

virtual int __stdcall DecodeValue (double Value) = ; 
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}; 

In questo esempio, si noti l'utilizzo di interface nella dichiarazione. Questa non e 

una vera parola chiave ma piuttosto una macro che viene utilizzata per convenzione 
con le interfacce. E mappata sulla parola chiave class. La macro INTERFACE_UUID 
assegna all'interfaccia un identificativo globalmente univoco (GUID). Si noti che la 
classe dell'interfaccia contiene solo metodi pure virtual. 

Prima che un'applicazione Web Service possa utilizzare questa interfaccia 
richiamabile, deve essere registrata con il file di registro delle chiamate. Sul server, Y 
elemento del registro delle chiamate consente al componente invoker 
(THTTPSOAPCppInvoker) di identificare una classe di implementazione da utilizzare 
per l'esecuzione delle chiamate all'interfaccia. Sulle applicazioni client, un elemento 
del registro delle chiamate permette agli oggetti remoti interfacciati (THTTPRio) di 
cercare informazioni che identifichino l'interfaccia richiamabile e forniscano 
informazioni su come chiamarla. 

Di solito, il client o il server Web Service crea il codice per definire le interfacce 
richiamabili o importando un documento WSDL o utilizzando il Web Service wizard. 
Per impostazione predefinita, quando l'importatore di WSDL o il Web Service 
wizard generano un'interfaccia, la definizione viene aggiunta a un file header avente 
lo stesso nome del Web Service. II corrispondente file .cpp contiene il codice per 
registrare l'interfaccia (oltre che una classe di implementazione nel caso si stia 
scrivendo un server). Per l'interfaccia descritta in precedenza, questo codice di 
registrazione assomiglia al seguente: 

static void RegTypesO 
{ 

InvRegistry()->RegisterInterface(__delphirtti(IEncodeDecode) , 11 ", "") ; 

} 

♦pragma startup RegTypes 32 

Le interfacce dei Web Service devono avere un namespace per identificarli tra tutte le 
interfacce in tutti i possibili Web Service. L'esempio precedente non fornisce un 
namespace per l'interfaccia. Quando non si fornisce esplicitamente un namespace, il 
file di registro delle chiamate ne genera automaticamente uno. Questo namespace e 
costituito da una stringa che identifica l'applicazione in modo univoco (la variabile 
AppNamespacePrefix), dal nome dell'interfaccia e dal nome della unit in cui e 
definita. Se non si desidera utilizzare il namespace generato in automatico, e 
possibile specificarne uno utilizzando esplicitamente un secondo parametro nella 
chiamata a Registerlnterface. 

Non tentare di utilizzare lo stesso file header che definisce un'interfaccia richiamabile 
sia nelle applicazioni client che server. Questo puo provocare facilmente 
incongruenze nei namespace, perche quando il file header viene incluso in un altro 
file sorgente, il nome della unit viene modificato in quello del file sorgente che 
include, modificando cosi il nome del namespace generato. Pertanto, le applicazioni 
client dovrebbero importare il Web Service utilizzando un documento WSDL. 
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Utilizzo di tipi non scalari nelle interfacce richiamabili 



L'architettura dei Web Services include automaticamente il supporto per lo 
smistamento dei tipi scalari seguenti: 

• bool 

• char 

• signed char 

• unsigned char 

• short 

• unsigned short 

• int 

• unsigned int 

• long 

• unsigned long 

• _int64 

• unsigned int64 

• float 

• double 

• long double 

• AnsiString 

• WideString 

• Currency 

• Variant 

Non sono necessarie operazioni particolari quando si utilizzano questi tipi in 
un'interfaccia richiamabile. Tuttavia, se l'interfaccia include qualche proprieta o 
metodo che utilizza altri tipi, l'applicazione deve registrare quei tipi con il registro 
dei tipi remotable. Per ulteriori informazioni sul registro dei tipi remotable, vedere 
"Registrazione di tipi non scalari" a pagina 36-5. 

I tipi enumerati e i tipi dichiarati con un'istruzione typedef richiedono una piccola 
operazione supplementare in modo che il registro dei tipi remotable possa estrarre 
dalla definizione del tipo le informazioni di tipo di cui ha bisogno. Queste sono 
descritte nella sezione "Registrazione di tipi dichiarati con typedef e di tipi 
enumerati" a pagina 36-6. 

I tipi dynamic array definiti in sysdyn.h vengono registrati automaticamente, e 
pertanto l'applicazione non deve aggiungere alcun codice di registrazione 
particolare. Uno di questi in particolare, TByteDynArray, merita una menzione 
speciale poiche mappa un blocco di dati binari 'base64', invece di mappare 
separatamente ogni elemento dell'array come fanno gli altri tipi di dynamic array. 

Per tutti gli altro tipi, come static array, struct o classi, e necessario mappare il tipo 
con una classe remotable. Una classe remotable e una classe che include informazioni 
di tipo in esecuzione (RTTI). L'interfaccia deve utilizzare quindi la classe remotable 
invece dell'array statico corrispondente, dello struct o della classe. Qualsiasi classe 
remotable si crei, la si deve registrare con il registro dei tipi remotable. 

Tutti i tipi dovrebbero essere dichiarati esplicitamente con un'istruzione typedef 
invece che essere dichiarati in linea. Cio e necessario in modo che il registro dei tipi 
remotable possa determinare il nome del tipo C++ native 
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Registrazione di tipi non scalari 

Prima che un'interfaccia richiamabile possa utilizzare un qualsiasi tipo diverso dai 
tipi scalari mativi elencati nella sezione "Utilizzo di tipi non scalari nelle interfacce 
richiamabili" a pagina 36-4, l'applicazione deve registrare il tipo con il registro dei 
tipi remotable. Per accedere al registro dei tipi remotable, e necessario includere 
InvokeRegistry.hpp nel file sorgente. Questo header dichiara una funzione globale, 
RemTypeRegistry (), che restituisce un riferimento al registro dei tipi remotable. 

Sui client, il codice per registrare i tipi con il registro di tipi remotable viene generato 
automaticamente quando si importa un documento WSDL. Per i server, i tipi 
remotable vengono registrati automaticamente quando si registra un'interfaccia che 
li utilizza. E necessario aggiungere esplicitamente il codice per registrare tipi solo se 
si desidera specificare il namespace o il nome del tipo invece di utilizzare i valori 
generati in automatico. 

II registro dei tipi remotable ha due metodi che e possibile utilizzare per registrare i 
tipi: RegisterXSInfo e RegisterXSClass. II primo (RegisterXSInfo) permette di registrare 
un array dinamico. II secondo (RegisterXSClass) serve per la registrazione di classi 
remotable che vengono definite per rappresentare altri tipi. 

Se si utilizzano array dinamici, il registro delle chiamate pud ottenere le informazioni 
di cui ha bisogno dalle informazioni di tipo generate dal compilatore. Cosi, ad 
esempio, l'interfaccia puo utilizzare un tipo come quello seguente: 

typedef DynamicArray<TXSDateTime> TDateTimeArray; 

Questo tipo viene registrato automaticamente quando si registra l'interfaccia 
richiamabile. Tuttavia, se si desidera specificare il namespace in cui il tipo e definite) o 
il nome del tipo, e necessario aggiungere la seguente registrazione alia funzione 
RegTypes usata per registrare l'interfaccia richiamabile che utilizza questo array 
dinamico: 

void RegTypes ( ) 
{ 

RemTypeRegistry ( ) ->RegisterXSInfo ( arraytypeinfo (TDateTimeArray) , 

MyNameSpace, "DTarray", "DTarray"); 
InvRegistry () ->Register Interface ( delphirtti (ITimeServices) ) ; 

} 

Non utilizzare piu tipi dynamic array che mappano tutti lo stesso tipo di elemento 
sottostante. Poiche il compilatore li tratta come tipi trasparenti che possono essere 
convertiti implicitamente in un altro tipo, non e in grado di distinguere le rispettive 
informazioni di tipo in esecuzione. 

II primo parametro di RegisterXSInfo e l'informazione di tipo per il tipo che si sta 
registrando. II secondo parametro e l'URI del namespace per il namespace in cui il 
tipo e definite Se si omette questo parametro o si fornisce una stringa vuota, il 
registro genera automaticamente un namespace. II terzo parametro e il nome del tipo 
come appare nel codice nativo C++. E necessario fornire un valore per questo 
parametro. L'ultimo parametro e il nome del tipo come appare nei documenti WSDL. 
Se si omette questo parametro o si fornisce una stringa vuota, il registro utilizza il 
nome del tipo nativo (il terzo parametro). 
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La registrazione di una classe remotable e simile, tranne per il fatto che si fornisce un 
riferimento di classe invece che un puntatore alle informazioni di tipo. Ad esempio, il 
seguente codice registra una classe remotable di nome TXSRecord: 

void RegTypes ( ) 

{ 

RemTypeRegistry()->RegisterXSclass(__classid (TXSRecord) , MyNameSpace, "record", "", 
false) ; 

InvRegistry()->RegisterInterface(__delphirtti (ITimeServices) ) ; 

} 

II primo parametro e il riferimento di classe per la classe remotable che rappresenta il 
tipo. II secondo e un identificativo uniforme di risorse (URI) che identifica in modo 
univoco il namespace della nuova classe. Se si fornisce una stringa vuota, il registro 
genera automaticamente un URI. II terzo e il quarto parametro specificano i nomi 
nativi ed esterni del tipo di dati che la classe rappresenta. Se si omette il secondo e il 
quarto parametro, il registro dei tipi utilizza il terzo parametro per entrambi i valori. 
Se si fornisce una stringa vuota per entrambi i parametri, il registro utilizza il nome 
della classe. II quinto parametro indica se il valore delle istanze della classe pud 
essere trasmesso come stringa. Volendo e possibile aggiungere un sesto parametro 
(non visualizzato qui) per controllare in che modo dovrebbero essere rappresentati 
nei pacchetti SOAP piu riferimenti alia stessa istanza dell'oggetto. 

Registrazione di tipi dichiarati con typedef e di tipi enumerati 

Se l'interfaccia richiamabile utilizza un tipo enumerato, la funzione delphirtti non 

e in grado di estrarre direttamente le sue informazioni di tipo. Per aggirare l'ostacolo, 
e necessario generare una classe contenitore in stile VCL che puo essere utilizzata per 
estrarre le informazioni di tipo per il tipo enumerato: 

class MyEnumType_TypeInfoHolder : public TObject { 

MyEnumType instanceType; 

public : 
..published : 

..property MyEnumType __propType = {read=__mstanceType }; 

}; 

In questo caso, la classe MyEnumType _TypelnfoHolder viene definita in modo da 
estrarre le informazioni di tipo da un tipo enumerato di nome MyEnumType. Ha una 

singola proprieta published, propType, il cui tipo e il tipo enumerato che si desidera 

registrare. Una volta definita la classe contenitore, e possibile ottenere le 
informazioni di tipo per il tipo enumerato chiamando la funzione globale 
GetClsMemberTypelnfo. II seguente codice illustra come registrare un tipo enumerato, 
data la sua classe detentrice: 

void RegTypes ( ) 

{ 

RemTypeRegistry ( ) ->RegisterXSInfo ( 

GetClsMemberTypelnfo (..classid (MyEnumType_TypeInfoHolder) , "..propType" ) , 
My Name Sp a c e , " My EnumTyp e " ) ; 

} 

RegisterClsMemberTypelnfo ha due parametri: Le informazioni di tipo della classe 
contenitrice e il nome della proprieta pubblicata dal cui tipo si desidera estrarre le 
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informazioni di tipo. Se la classe contenitrice ha solo una proprieta pubblicata (come 
nell'esempio precedente), e possibile omettere il secondo parametro. 

Questa tecnica di utilizzare una classe contenitrice deve essere utilizzata anche se il 
tipo e dichiarato utilizzando un'istruzione typedef che lo mappa con un tipo scalare 
nativo di C++. ( un tipo scalare nativo di C++ e un qualunque tipo fra quelli elencati 
in "Utilizzo di tipi non scalari nelle interfacce richiamabili" a pagina 36-4 tranne per 
quelli che sono classi che emulano i tipi Object Pascal). Percid, ad esempio, dato il 
seguente tipo: 

typedef int CardNumber; 
Si dovrebbe creare una classe contenitrice come quella seguente: 

class CardNumberType_TypeInfoHolder : public TObject { 

CardNumber __instanceType; 
public : 
__published : 

__property CardNumber __propType = {read=__instanceType }; 

}; 

e quindi registrarla come segue: 

RemTypeRegistry ( ) ->RegisterXSInf o (GetClsMemberTypelnf o ( 

__classid (CardNumber_TypeInfoHolder) , "__propType" ) , 
MyNameSpace, "CardNumber"); 

Per qualsiasi altro tipo dichiarato utilizzando un'istruzione typedef, chiamare 
RegisterXSInfo se e mappato su una classe di array dinamico, e RegisterXSClass se e 
mappato con una classe. Per ulteriori informazioni sulla registrazione di array 
dinamici e classi, vedere "Registrazione di tipi non scalari" a pagina 36-5. 

Si dovrebbe cercare di evitare istruzioni typedef che mappano piu tipi con lo stesso 
tipo sottostante. Le informazioni di tipo in esecuzione per questi non sono 
distinguibili. 



Utilizzo di oggetti remotable 

Utilizzare TRemotable come classe di base quando si definisce una classe per 
rappresentare un tipo di dati complesso su un'interfaccia richiamabile. Ad esempio, 
nel caso in cui di solito si passerebbe come parametro uno struct, si potrebbe invece 
definire un discendente Tremotable, in cui ogni membro dello struct e una proprieta 
pubblicata della nuova classe. 

E possibile controllare se le proprieta pubblicate del discendente TRemotable 
appaiono come nodi di elemento o attributi nella corrispondente codifica SOAP del 
tipo. Per trasformare una proprieta in un attributo, utilizzare la direttiva stored sulla 
definizione della proprieta, assegnando un valore di AS_ATTRIBUTE: 

property bool MyAttribute = 

{read=FMyAttribute, write=FMyAttribute, stored= AS_ATTRIBUTE; 

Se non si include una direttiva stored o se si assegna un qualsiasi altro valore alia 
direttiva stored (anche una funzione che restituisce AS_ATTRIBUTE), la proprieta 
viene codificata come un nodo piuttosto che come un attributo. 
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Se il valore del nuovo discendente TRemotable rappresenta un tipo scalare in tin 
documento WSDL, come classe di base si dovrebbe utilizzare invece TRemotableXS . 
TRemotableXS e un discendente di TRemotable che introduce due metodi per la 
conversione della nuova classe nella sua rappresentazione di stringa. Implementare 
questi metodi ridefinendo i metodi XSToNative e NativeToXS. 

Per alcuni tipi scalari di XML comunemente usati, la unit XSBuiltlns def inisce e 
registra automaticamente una serie di classi remotable. Queste sono elencate nella 
seguente tabella: 



Tabella 36.1 Classi Remotable 

classe remotable 

TXSDateTime 



Tipo XML 

dateTime 
timelnstant 

data 

tempo 

durata 

timeDuration 

decimale 

hexBinary 



TXSDate 
TXSTime 
TXSDuration 

TXSDecimal 
TXSHexBinary 



Dopo avere definito una classe remotable, la si deve registrare con il registro dei tipi 
remotable, come descritto in "Registrazione di tipi non scalari" a pagina 36-5.Questa 
registrazione awiene automaticamente su server quando si registra l'interfaccia che 
utilizza la classe. Sui client, il codice per registrare la classe viene generato 
automaticamente quando si importa il documento WSDL che definisce il tipo. 

E buona norma implementare e registrare i discendenti TRemotable in una unit 

_U | separata dal resto dell'applicazione server, includendo dalle unit che dichiarano e 

registrano le interfacce richiamabili. In questo modo, e possibile utilizzare il tipo per 
piu di un'interfaccia. 

Un problema che si presenta quando si utilizzano discendenti di TRemotable e il 
momento in cui tali discendenti vengono creati e distrutti. Ovviamente, 
l'applicazione server deve creare la propria istanza locale di questi oggetti, poiche 
l'istanza del chiamante e in uno spazio di processo separata. Per gestire cio, le 
applicazioni Web Services creano un contesto di dati per le richieste in arrivo. II 
contesto di dati persiste mentre il server gestisce la richiesta e viene liberato dopo che 
ogni parametro di output e stato smistato in un messaggio di ritorno. Quando il 
server crea istanze locali di oggetti remotable, li aggiunge al contesto di dati e quelle 
istanze vengono quindi liberate insieme al contesto di dati. In alcuni casi, si potrebbe 
volere evitare che un'istanza di un oggetto remotable venga liberata dopo una 
chiamata a metodo. Ad esempio, se l'oggetto contiene informazioni di stato, potrebbe 
essere piu eff iciente avere una singola istanza che viene utilizzato per ogni chiamata 
di messaggio. Per evitare che l'oggetto remotable venga liberato insieme al contesto 
di dati, modificarne la proprieta DataContext. 
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Esempio di oggetto Remotable 

Questo esempio mostra come creare un oggetto remotable per un parametro su 
un'interfaccia richiamabile dove altrimenti si utilizzerebbe una classe esistente. In 
questo esempio, la classe esistente e un elenco di stringhe (TStringList). Per limitare le 
dimensioni dell'esempio, non viene riprodotta la proprieta Objects dell'elenco di 
stringhe. 

Poiche la nuova classe non e scalare, essa deriva da TRemotable invece che da 
TRemotableXS. Include una proprieta pubblicata per ogni proprieta dell'elenco di 
stringhe che si desidera comunicare tra il client e il server. Ognuna di queste 
proprieta remotable corrisponde a un tipo remotable. Inoltre, la nuova classe 
remotable include metodi per effettuare la conversione da un elenco di stringhe e 
viceversa. 

class TRemotableStrmgList : public TRemotable 

{ 

private : 
bool FCaseSensitive; 
bool FSorted; 

Classes: :TDuplicates FDuplicates ; 
System: :TStringDynArray FStrings; 
public : 

void __fastcall Assign(Classes: :TStringList *SourceList ) ; 
void __fastcall AssignTo (Classes: :TStringList *DestList); 
..published : 

__property bool CaseSensitive = {read=FCaseSensitive, write=FCaseSensitive} ; 
__property bool Sorted = {read=FSorted, write=FSorted} ; 

__property Classes: :TDuplicates Duplicates = {read=FDuplicates, write=FDuplicates} ; 
__property System: :TStringDynArray Strings = {read=FStrings, write=FStrings} ; 

} 

Si noti che TRemotableStringList esiste solo come classe di trasporto. Pertanto, benche 
abbia una proprieta Sorted (per trasportare il valore di una proprieta Sorted di un 
elenco di stringhe), non e necessario che ordini le stringhe che memorizza ma deve 
solo memorizzare se le stringhe devono essere ordinate o meno. In questo modo 
l'implementazione risulta molto semplice. E necessario solo implementare i metodi 
Assign e Assign To , che si convertono da un elenco di stringhe e viceversa: 

void __fastcall TRemotableStrmgList: : Assign (Classes : :TStringList *SourceList) 

{ 

SetLengthfStrings, SourceList->Count ) ; 

for (int i = 0; i < SourceList->Count; i++) 

Strings [i] = SourceList->Strings [i] ; 
CaseSensitive = SourceList->CaseSensitive; 
Sorted = SourceList->Sorted; 
Duplicates = SourceList->Duplicates; 

} 

void __fastcall TRemotableStringList: :AssignTo(Classes: :TStringList *DestList) 

{ 

DestList->Clear() ; 

DestList->Capacity = Length ( Strings ) ; 
DestList->CaseSensitive = CaseSensitive; 
DestList->Sorted = Sorted; 
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DestList->Duplicates = Duplicates; 
for (int i = 0; i < Length ( Strings ) ; i++) 
DestList->Add (Strings [i] ) ; 

} 

Facoltativamente, si potrebbe volere registrare la nuova classe remotable in modo 
che sia possibile specificare il suo nome di classe. Se non si registra la classe, essa 
viene registrato automaticamente quando si registra l'interfaccia che la utilizza. Alio 
stesso modo, se si registrano la classe ma non i tipi TDuplicates e TStringDyn Array che 
essa utilizza, essi vengono registrati automaticamente. II codice seguenete mostra 
come registrare la classe TRemotableStringList. TStringDyn Array viene registrato 
automaticamente perche e uno dei tipi array dinamici nativi dichiarati in sysdyn.h. 
Per i dettagli sulla registrazione esplicita di un tipo enumerato come TDuplicates, 
vedere "Registrazione di tipi dichiarati con typedef e di tipi enumerati" a 
pagina 36-6. 

void RegTypes ( ) 
{ 

RemTypeRegistry()->RegisterXSclass(__classid (TRemotableStringList) , MyNameSpace, 
"stringList" , "", false); 

} 

tpragma startup initServices 32 

Scrittura di server che supportano i Web Services 



Oltre alle interfacce richiamabili e alle classi discendenti che implementano i 
rispettivi metodi pure virtual, il server richiede due componenti: un dispatcher e un 
invoker. II dispatcher (THTTPSoapDispatcher) riceve i messaggi SOAP in arrivo e li 
passa all'invoker. L'invoker (THTTPSoapCppInvoker) interpreta il messaggio SOAP, 
identifica l'interfaccia richiamabile che esso chiama, esegue la chiamata e assembla il 
messaggio di risposta. 

THTTPSoapDispatcher e THTTPSoapCppInvoker sono progettati per rispondere a 
messaggi HTTP che contengono una richiesta SOAP. L'architettura sottostante e 
sufficientemente generale, tuttavia, che e in grado di supportare altri protocolli che 
utilizzano componenti dispatcher e invoker differenti. 

Una volta che si registrano le interfacce richiamabili e le loro classi di 
implementazione, il dispatcher e l'invoker gestiscono automaticamente qualsiasi 
messaggio che identifica quelle interfacce nell' Action header di SOAP Action del 
messaggio di richiesta HTTP. 

I Web Service includono anche un publisher (TWSDLHTMLPublish). I publisher 
rispondono alle richieste dei client in arrivo creando i documenti WSDL che 
descrivono come chiamare i Web Services nell'applicazione. 

Creazione di un server Web Service 



Per creare un'applicazione server che implementa un Web Service fare quanto segue: 
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1 Scegliere File I New I Other e sulla pagina WebServices, fare doppio clic sull'icona 
Soap Server Application per avviare il SOAP Server Application wizard. II wizard 
crea una nuova applicazione Web server che include i componenti necessari per 
rispondere alle richieste SOAP. Per i dettagli sul wizard per le applicazioni SOAP 
e sul codice che esso genera, vedere "Utilizzo di SOAP application wizard" a 
pagina 36-11. 

2 Quando si esce da SOAP Server Application wizard, viene chiesto se si desidera 
definire un'interfaccia per il Web Service. Se si sta creano un web Service da zero, 
facendo clic su Yes si vedra apparire il wizard Add New Web Service. II wizard 
aggiunge il codice per dichiarare e registrare una nuova interfaccia richiamabile 
per il Web Service. Editare il codice generato per definire e implementare il Web 
Service. Se si desidera aggiungere altre interfacce (o si desidera definire le 
interfacce in un momento successivo), scegliere File I New I Other e, sulla pagina 
WebServices, fare doppio clic sull'icona SOAP Web Service interface. Per i dettagli 
sull'uso del wizard Add New Web Service e sul completamento del codice 
generato, vedere "Aggiunta di nuovi Web Services" a pagina 36-12. 

3 Se si sta implementando un Web Service che e stato gia definito in un documento 
WSDL, e possibile utilizzare Web Services Importer per generare le interfacce, le 
classi di implementazione e il codice di registrazione necessari all'applicazione. E 
sufficiente solo completare il corpo dei metodi che l'importatore genera per le 
classi di implementazione. Per i dettagli sull'utilizzo di Web Services Importer, 
vedere "Utilizzo di Web Services Importer" a pagina 36-14. 

4 Se l'applicazione solleva un'eccezione nel momento in cui tenta di eseguire una 
richiesta SOAP, l'eccezione verra codificata automaticamente in un pacchetto di 
errore SOAP, che sara restituito al posto dei risultati della chiamata al metodo. Se 
si vogliono ottenere maggiori informazioni al posto di un semplice messaggio di 
errore, e posisbile creare delle classi di eccezione che saranno codificate e passate 
al client. L'operazione e descritta in "Creazione di classi di eccezione custom per 
Web Services" a pagina 36-15. 

5 SOAP Server Application wizard aggiunge alle nuove applicazioni Web Service 
un componente publisher (TWSDLHTMLPublish ). Cio permette all'applicazione 
di pubblicare documenti WSDL che descrivono il Web Service ai client. Per 
informazioni sul publisher WSDL, vedere "Generazione di documenti WSDL per 
un'applicazione Web Service" a pagina 36-16. 

Utilizzo di SOAP application wizard 



Le applicazioni Web Service sono una forma particolare di applicazioni Web Server. 
Per questo motivo, il supporto per Web Services e costruito sopra all'architettura 
Web Broker. Pertanto, per capire il codice generato da SOAP Application wizard, e 
utile per capire l'architettura Web Broker. Le informazioni sulle applicazioni per Web 
server in generale e su Web Broker in particolare, sono reperibili nel Capitolo 32, 
"Creazione di applicazioni server per Internet" e nel Capitolo 33, "Utilizzo di Web 
Broker". 

Per avviare SOAP application wizard, scegliere File I New I Other e sulla pagina 
WebServices, fare doppio clic sull'icona Soap Server Application. Scegliere il tipo di 
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applicazione per Web server che si desidera utilizzare per il Web Service. Per 
informazioni sui vari tipi di applicazioni per Web server, vedere "Tipi di applicazioni 
per server Web" a pagina 32-7. 

II wizard genera una nuova applicazione per Web server che include un modulo 
Web che contiene tre componenti: 

• Un componente invoker (THTTPSOAPCppInvoker). L'invoker effettua la 
conversione tra i messaggi SOAP e i metodi di una qualunque interfaccia 
richiamabile registrata nell'applicazione Web Service. 

• Un componente dispatcher (THTTPSoapDispatcher). II dispatcher risponde 
automaticamente ai messaggi SOAP in arrivo e li invia all'invoker. E possibile 
utilizzare la sua proprieta WebDispatch per identificare i messaggi di richiesta 
HTTP a cui l'applicazione risponde. Cio implica l'impostazione della proprieta 
Pathlnfo per indicare la parte di percorso di un qualunque URL indirizzato 
all'applicazione e della proprieta MethodType per indicare l'header del metodo per 
i messaggi di richiesta. 

• Un editor WSDL (TWSDLHTMLPublish). L'editor WSDL pubblica un documento 
WSDL che descrive le interfacce e la modalita con cui chiamarle. II documento 
WSDL dice ai client come effettuare la chiamata all'applicazione Web Service. Per i 
dettagli sull'utilizzo dell'editor WSDL, vedere "Generazione di documenti WSDL 
per un'applicazione Web Service" a pagina 36-16. 

II dispatcher SOAP e l'editor WSDL sono componenti auto-dispatching. Questo 
significa che essi si registrano automaticamente con il modulo Web in modo che 
inoltri qualsiasi richiesta in arrivo indirizzata utilizzando le informazioni di percorso 
che essi specificano nelle rispettive proprieta WebDispatch. Se si fa clic destro sul 
modulo Web, e possibile vedere che, oltre a questi componenti auto-dispatching, ha 
un singolo elemento di azione Web di nome DefaultHandler. 

DefaultHandler e l'elemento di azione predefinito. Cioe, se il modulo Web riceve una 
richiesta per la quale non e in grado di trovare un gestore (non e in grado di trovare 
una corrispondenza con le informazioni di percorso), invia quel messaggio 
all'elemento di azione predefinito. DefaultHandler genera una pagina web che 
descrive il Web Service. Per modificare l'azione predefinita, modificare il gestore di 
evento OnAction dell'elemento di azione. 

Aggiunta di nuovi Web Services 



Per aggiungere all'applicazione server una nuova interfaccia Web Service, scegliere 
File I New I Other e sulla pagina WebServices fare doppio clic sull'icona SOAP Server 
Interface. 

II wizard Add New Web Service consente di specificare il nome dell'interfaccia 
richiamabile che si desidera esporre ai client e genera il codice per dichiarare e 
registrare l'interfaccia e la sua classe di implementazione da essa derivata. Per 
impostazione predefinita, il wizard genera anche commenti che mostrano i metodi di 
esempio e le definizioni di tipo aggiuntive, che aiutano a iniziare l'editing dei file 
generati. 
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Editing del codice generate 

Le definizioni dell'interfaccia appaiono nel file header della unit generata, il cui 
nome e quello che era stato specificato utilizzando il wizard. Si vorra modificare la 
dichiarazione deH'interfaccia, sostituendo i metodi di esempio con i metodi che si 
stanno rendendo disponibili ai client. 

II wizard genera una classe di implementazione che discende da TInvokableClass e 
dall'interfaccia richiamabile. Se si sta definendo da zero un'interfaccia richiamabile, e 
necessario modifocare la dichiarazione della classe di implementazione in kodo che 
corrisponda alle eventuali modifiche apportate all'interfaccia richiamabile generata. 

Quando si aggiungono metodi all' interfaccia richiamabile e alia classe di 
implementazione, e bene ricordare che i metodi devono utilizzare solo tipi 
remotable. Per informazioni sui tipi remotable e sulle interfacce richiamabili, vedere 
"Utilizzo di tipi non scalari nelle interfacce richiamabili" a pagina 36-4. 

Utilizzo di una classe di base differente 

II wizard Add New Web Service genera classi di implementazione che discendono 
da TInvokableClass. Questo e il modo piu semplice per creare una nuova classe per 
implementare un Web Service. E possibile, tuttavia, sostituire questa classe generata 
con una classe di implementazione che ha una classe di base differente (ad esempio, 
si potrebbe volere utilizzare come una classe base una classe esistente). Quando si 
sostituisce la classe di implementazione generata, e bene fare alcune considerazioni: 

• La nuova classe di implementazione deve discendere direttamente dall'interfaccia 
richiamabile. II registro delle chiamate, con cui si registrano le interfacce 
richiamabili e le loro classi di implementazione, tiene traccia delle classi 
implementate da ogni interfaccia registrata e la rende disponibile al componente 
invoker nel momento in cui l'invoker ha la necessita di chiamare l'interfaccia. Puo 
rilevare che una classe implementa un'interfaccia solo se l'interfaccia e inclusa 
direttamente nella dichiarazione della classe. Non e in grado di supportare 
un'interfaccia nel caso sia stata ereditato insieme a una classe base. 

• La nuova classe di implementazione deve includere il supporto per i metodi 
IUnknown che fanno parte di una qualsiasi interfaccia. Questo punto puo 
sembrare ovvio, ma e molto facile trascurarlo. Per ulteriori informazioni su 
IUnknown, vedere "Creazione di classi che supportano IUnknown" a pagina 13-4. 

• E necessario modificare il codice generato che registra la classe di 
implementazione in mod da includere un metodo factory per creare le istanze 
della classe di implementazione. 

Quest'ultimo punto richiede qualche spiegazione. Quando la classe di 
implementazione discende da TInvokableClass e non sostituisce il costruttore ereditato 
con un nuovo costruttore che include uno o piu parametri, il registro delle chiamate 
sa come creare le istanze della classe nel momento in cui ne ha bisogno. Quando si 
scrive una classe di implementazione che non discende da TInvokableClass o quando 
si modifica il costruttore, e necessario dire al registro delle chiamate in che modo 
ottenere le istanze della classe di implementazione. 

E possibile dire al registro delle chiamate come ottenere le istanze della classe di 
implementazione fornendolo di una procedura factory. Anche se si ha una classe di 
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implementazione che discende da TInvokableClass e che utilizza il costruttore 
ereditato, e comunque possibile fornire una procedure factory. Ad esempio, invece di 
richiedere al registro delle chiamate di creare una nuova istanza ogni volta che 
l'applicazione riceve una chiamata all'interfaccia richiamabile, e possibile utilizzare 
una singola istanza globale della classe di implementazione. 

La procedura factory deve essere di tipo TCreatelnstanceProc. Essa restituisce 
un'istanza della classe di implementazione. Se la procedura crea una nuova istanza, 
dato che il registro delle chiamate non libera esplicitamente le istanze degli oggetti, 
l'oggetto di implementazione dovrebbe liberarsi da solo nel momento in cui il 
contatore dei riferimenti sulla sua interfaccia arriva a zero. II codice seguente illustra 
un altro metodo, in la procedura factory restituisce una singola istanza globale della 
classe di implementazione: 

void __fastcall CreateEncodeDecode (System: :T0bject* &obj) 

{ 

if (! FEncodeDecode) 

{ 

FEncodeDecode = new TEncodeDecodelmpl!); 

// save a reference to the interface so that the global instance doesn't free itself 
TEncodeDecodeImpl->Query Interface (FEncodeDecodelnterface) ; 

} 

obj = FEncodeDecode; 

} 

Nell'esempio precedente, FEncodeDecodelnterface e una variabile di tipo 
_di_IEncodeDecode. 

Si registra la procedura di fabbrica con una classe di implementazione fornendola 
come secondo parametro alia chiamata che registra la classe con il registro delle 
chiamate. Individuare Per prima cosa, si deve individuare la chiamata che il wizard 
ha generato per registrare la classe di implementazione. Questa apparira nel metodo 
RegTypes alia fine della unit che definisce la classe. Dovrebbe assomigliare a 
qualcosa del genere: 

invRegistry ( ) ->RegisterlnvokableClass ( classid (TEncodeDecodelmpl) ) ; 

Aggiungere a questa chiamata un secondo parametro che specifichi la procedura 
factory: 

InvRegistry ( ) ->RegisterlnvokableClass (__classid (TEncodeDecodelmpl) , SCreateEncodeDecode) ; 

Utilizzo di Web Services Importer 



Per utilizzare Web Services Importer, scegliere File I New I Other e alia pagina 
WebServices fare doppio clic sull'icona Web Services Importer. Nella finestra di 
dialogo visualizzata, specificare il nome di file di un documento WSDL (o di un file 
XML) oppure specificare l'URL in cui quel documento e pubblicato. 

Se il documento WSDL e su un server che necessita di autenticazione (o deve essere 
raggiunto utilizzando un proxy server che richiede l'autenticazione), prima che il 
wizard possa acquisire il documento WSDL e necessario fornire un nome utente e 
una password. Per fornire queste informazioni, fare clic sul pulsante Options e 
fornire le opportune informazioni di connessione. 
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Quando si fa clic sul pulsante Next, Web Services Importer mostra il codice, 
compatibile con il framework di Web Services, che esso genera per ogni definizione 
nel documento WSDL. Cio significa che utilizza solo quei tipi di porta che hanno un 
binding SOAP. Facendo clic sul pulsante Options e scegliendo le opzioni desiderate, 
e possibile configurare il modo in cui l'importatore genera il codice. 

Web Services Importer puo essere utilizzato quando si scrive un server o 
un'applicazione client. Quando si scrive un server, fare clic sul pulsante Options e 
nella finestra di dialogo risultante, attivare l'opzione che dice all'importatore di 
generare i codice per il server. Quando si seleziona questa opzione, l'importatore 
genera le classi di implementazione per le interfacce richiamabili ed e necessario solo 
completare i corpi dei metodi. 

Se si importa un documento WSDL per creare un server che implementa un Web 
Service che e gia stato definito, e sempre necessario pubblicare il documento WSDL 
per quel servizio. Fra il documento WSDL importato e l'implementazione generata vi 
possono essere delle differenze secondarie. Ad esempio, se il documento WSDL o file 
di schema XML utilizza identificativi che sono anche parole chiave del linguaggio 
C++, l'importatore adatta automaticamente i loro nomi in modo che il codice 
generato possa essere compilato.) 

Non appena si fa clic su Finish, l'importatore crea nuove unit che definiscono e 
registrano le interfacce richiamabili per le operazioni definite nel documento, e che 
definiscono e registrano le classi remotable per i tipi definiti dal documento. 

Come metodo alternative, e possibile utilizzare invece l'importer WSDL per la riga 
comandi. Per un server, chiamare l'importatore della riga comandi con l'opzione -S, 
nel seguente modo: 

WSDLIMP -S -C -V MyWSDLDoc.wsdl 

Per un'applicazione client, chiamare l'importatore della riga comandi senza 
l'opzione -S: 

WSDLIMP -C -V MyWSDLDoc.wsdl 

Creazione di classi di eccezione custom per Web Services 



Nel caso l'applicazione Web Service sollevi un'eccezione mentre sta cercando di 
eseguire una richiesta SOAP, essa codifica automaticamente le informazioni per 
quell'eccezione in un pacchetto di errore SOAP, che viene restituito al posto dei 
risultati della chiamata al metodo. L'applicazione client quindi solleva l'eccezione. 

Per impostazione predefinta, l'applicazione client solleva un'eccezione generica di 
tipo ERemotableExceptionwith con le informazioni relative al pacchetto di errore 
SOAP. Se si deriva un discendente ERemotableException, e possibile trasmettere 
ulteriori informazioni specifiche per l'applicazione. I valori di tutte le proprieta 
pubblicate che vengono aggiunte alia classe di eccezione vengono inclusi nel 
pacchetto di errore SOAP in modo che il client possa sollevare un'eccezione 
equivalente. 

Per utilizzare un discendente di ERemotableException , e necessario registrarlo con il 
registro dei tipi remotable. Nella unit che definisce il discendente di 
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ERemotableException e necessario includere InvokeRegistry.hpp e aggiungere una 
chiamata al metodo RegisterXSClass dell'oggetto restituito dalla funzione globale 
RemTypeRegistry. 

Se anche il client definisce e registra il discendente di ERemotableException, quando 
riceve il pacchetto di errore SOAP, solleva automaticamente un'istanza della classe di 
eccezione appropriata, con tutte le proprieta impostate ai valori inclusi nel pacchetto 
di errore SOAP. 

Generazione di documenti WSDL per un'applicazione Web Service 



Per consentire alle applicazioni client di sapere quali sono i Web Services resi 
disponibili dall'applicazione, e possibile pubblicare un documento WSDL che 
descrive le interfacce richiamabili e indica come chiamarle. 

E sempre necessario pubblicare un documento WSDL per l'applicazione Web 
Service, anche se si e implementato un servizio importato o se il client e stato scritto 
utilizzando C++Builder. 

Per pubblicare un documento WSDL che descrive il Web Service, includere nel Web 
Module un componente TWSDLHTMLPublish. (SOAP Server Application wizard 
aggiunge questo componente automaticamente). TWSDLHTMLPublish e un 
componente auto-dispatching, il che significa che risponde automaticamente ai 
messaggi in arrivo che richiedono un elenco di documenti WSDL per il Web Service. 
Per specificare le informazioni di percorso dell'URL che i client devono utilizzare per 
accedere all'elenco di documenti WSDL, utilizzare la proprieta WebDispatch. II Web 
browser puo richiedere quindi l'elenco dei documenti WSDL specificando un'URL 
che e costituito dall'ubicazione dell'applicazione server seguita dal percorso 
specificato nella proprieta WebDispatch. L'URL assomiglia a quello mostrato di 
seguito: 

http : //www. myco .com/MyService.dll /WSDL 

Se si desidera invece utilizzare un file fisico WSDL, e possibile visualizzare il 
documento WSDL nel Web browser e quindi salvarlo in modo da generare un file di 
documento WSDL. 

Non e necessario pubblicare il documento WSDL dalla stessa applicazione che 
implementa il Web Service. Per creare un'applicazione che si limita a pubblicare il 
documento WSDL, omettere il codice che implementa e registra gli oggetti di 
implementazione e includere solo il codice che definisce e registra le interfacce 
richiamabili, le classi remotable che rappresentano i tipi complessi e le eventuali 
eccezioni remotable. 

Per impostazione predefinita, quando si pubblica un documento WSDL, esso indica 
che i servizi sono disponibili alio stesso URL su cui e stato pubblicato il documento 
WSDL (anche se con un percorso diff rente). Se si stanno distribuendo piu versioni 
dell'applicazione Web Service oppure se si pubblica il documento WSDL da 
un'applicazione diversa da quella che implementa il Web Service, sara necessario 
modificare il documento WSDL in modo che includa le informazioni aggiornate su 
dove individuare il Web Service. 
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Per modificare l'URL, utilizzare il WSDL administrator. La prima operazione 
consiste nell'attivare ramministratore. L'operazione viene condotta impostando la 
proprieta AdminEnabled del componente TWSDLHTMLPublish a true. In seguito, 
quando si utilizzera il browser per visualizzato l'elenco dei documenti WSDL, esso 
includera anche un pulsante che ne consentira la gestione. Utilizzare il WSDL 
administrator per specificare le ubicazioni (URL) su cui e stata distribuita 
l'applicazione Web Service. 

Scrittura di client per Web Services 



C++Builder fornisce un supporto sul lato client per chiamare i Web Services che 
utilizzano un binding basato su SOAP. Questi Web Services possono essere forniti da 
un server scritto in C++Builder o da un qualsiasi altro server che definisce il proprio 
Web Service mediante un documento WSDL. 

Importazione di documenti WSDL 



Prima di potere utilizzare un Web Service, l'applicazione deve definire e registrare le 
interfacce e i tipi richiamabili inclusi nell'applicazione Web Service. Per ottenere 
queste definizioni, e possibile importare un documento WSDL (o un file XML) che 
definisce il servizio. Web Services crea una unit che definisce e registra le interfacce e 
i tipi che e necessario utilizzare. Per i dettagli sull'utilizzo di Web Services Importer, 
vedere "Utilizzo di Web Services Importer" a pagina 36-14. 

Chiamata a interfacce richiamabili 



Per chiamare un'interfaccia richiamabile, l'applicazione client deve includere tutti gli 
header che definiscono le interfacce richiamabili e tutte le classi remotable che 
implementano tipi complessi. 

Una volta che l'applicazione client ha la dichiarazione di un'interfaccia richiamabile, 
creare un'istanza di THTTPRio per l'interfaccia desiderata: 

X = new THTTPRio (NULL) ; 

E importante che non si distrugga esplicitamente l'istanza di THTTPRio. Se e stato 
creato senza un Owner (come nella riga di codice vista in precedenza), esso si libera 
automaticamente non appena viene rilasciata la sua interfaccia. Se e stato creato con 
un Owner, e YOwner che si fa carico di liberare l'istanza di THTTPRio. 

Quindi, fornire all'oggetto THTTPRio le informazioni necessarie per identificare 
l'interfaccia del server e individuare il server. Vi sono due modi per fornire queste 
informazioni: 

• Se non si fa affidamento sull'URL per il Web Service o sui namespace e sugli 
header Soap che l'oggetto deve modificare, e possibile specificare semplicemente 
l'URL per il Web Service a cui si vuole accedere. THTTPRio utilizza questo URL 
per cercare la definizione dell'interfaccia, oltre a tutte le informazioni sui 
namespace e sgli header, in base alle informazioni contenute nel registro delle 
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chiamate. Specificare l'URL impostando la proprieta URL all'ubicazione del 
server: 

X->URL = "http: //www. myco .com/MyService. dll/ SOAP/ IServerlnt erf ace" ; 

• Se si desidera cercare dinamicamente in fase di esecuzione l'URL, il namespace o il 
Soap Action header nel documento WSDL, e possibile utilizzare le proprieta 
WSDLLocation, Service e Port e l'oggetto estrarra le informazioni necessarie dal 
documento WSDL: 

X. WSDLLocation = " Cryptography. wsdl " ; 
X. Service = "Cryptography"; 
X.Port = "SoapEncodeDecode" ; 

Una volta che si e specificato come individuare il server e identificare l'interfaccia, e 
possibile utilizzare il metodo Querylnterface per ottenere un puntatore all'interfaccia 
per l'interfaccia richiamabile. In questo modo viene creata dinamicamente in 
memoria una vtable per l'interfaccia associata, consentendo cosi di effettuare 
chiamate all'interfaccia: 

_di_lEncodeDecode interfaceVariable; 
X->QueryInterface (InterfaceVariable) ; 
if (InterfaceVariable) 

{ 

Code = lnterfaceVariable->EncodeValue (5) ; 

} 

Notare che la chiamata a Querylnterface accetta come argomento il wrapper 
Delphilnterface per l'interfaccia richiamabile al posto della stessa interfaccia 
richiamabile. 

THTTPRio si basa sul registro delle chiamate per ottenere le informazioni relative 
all'interfaccia richiamabile. Se l'applicazione client non ha un registro delle chiamate 
o se l'interfaccia richiamabile non e registrata, THTTPRio non puo costruire la 
propria vtable in memoria. 

Se si assegna a una variabile globale l'interfaccia che si ottiene da THTTPRio, prima 
di chiudere l'applicazione e necessario modificare quell'assegnazione a NULL. Ad 
esempio, se InterfaceVariable nell'esempio di codice precedente fosse una variabile 
globale invece che una variabile di stack, sarebbe necessario rilasciare l'interfaccia 
prima che l'oggetto THTTPRio venga liberate Di solito, questo codice va nel gestore 
di evento OnDestroy della scheda o del modulo dati: 

void __fastcall TForml: :FormDestroy (TObject *Sender) 

{ 

InterfaceVariable = NULL; 

} 

II motivo per cui e necessario riassegnare a una variabile di interfaccia globale il 
valore NULL sta nel fatto che THTTPRio costruisce dinamicamente in memoria la 
propria vtable. Quella vtable deve essere ancora presente quando l'interfaccia viene 
rilasciata. Se non si rilascia l'interfaccia insieme alia scheda o al modulo dati, essa 
viene rilasciata quando la variabile globale viene liberata al momento della chiusura. 
La memoria per le variabili globali puo essere liberata dopo la scheda o il modulo 
dati che contiene l'oggetto THTTPRio, nel qual caso la vtable non sara disponibile 
quando viene rilasciata l'interfaccia. 
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37 



Operazioni 



con i socket 



Questo capitolo descrive i componenti socket che consentono di creare 
un'applicazione che, grazie a TCP/IP e ai relativi protocolli, e in grado di comunicare 
con altri sistemi. Grazie ai socket, e possibile leggere e scrivere su altre macchine 
connesse senza preoccuparsi dei dettagli del software di rete sottostante. I socket 
forniscono connessioni basate sul protocollo TCP/IP, ma sono sufficientemente 
generici da operare con protocolli analoghi quali User Datagram Protocol (UDP), 
Xerox Network System (XNS), DECnet di Digital, o la famiglia IPX/SPX di Novell. 

L'utilizzo dei socket consente di scrivere applicazioni server o client di rete che 
leggono e scrivono su altri sistemi. Un'applicazione server o client e solitamente 
dedicata a un singolo servizio, quale Hypertext Transfer Protocol (HTTP) o File 
Transfer Protocol (FTP). Grazie ai socket server, un'applicazione in grado di fornire 
uno di questi servizi puo effettuare un collegamento con applicazioni client che 
vogliono usare quel servizio. I socket client permettono di collegare un'applicazione 
che usa uno di questi servizi alle applicazioni server che lo forniscono. 



I socket forniscono uno degli elementi necessari per scrivere applicazioni server o 
client di rete. Per molti servizi, quali ad esempio HTTP o FTP, sono gia disponibili 
server di terze parti. Alcuni sono addirittura incorporati nel sistema operative per 
cui non occorre nemmeno scriverli. Comunque, quando si vuole un maggior 
controllo sul modo in cui il servizio viene implementato, o un'integrazione piu stretta 
tra la propria applicazione e la comunicazione di rete, o quando non e disponibile 
alcun server per quel determinato servizio di cui si ha bisogno, e possibile creare 
un'applicazione server o client personalizzata. Per esempio, quando si opera con 
dataset distribuiti, e possibile scrivere uno strata per comunicare con database posti 
su altri sistemi. 



Implementazione dei servizi 
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I protocolli di servizio 



Prima di poter scrivere un server o un client di rete, occorre capire il servizio che 
l'applicazione deve fornire o utilizzare. Molti servizi hanno protocolli standard che 
devono essere supportati dall'applicazione di rete. Se si sta scrivendo 
un'applicazione di rete per un servizio standard quale, ad esempio, HTTP, FTP, o 
anche Finger o Time, occorre anzitutto capire i protocolli usati per comunicare con gli 
altri sistemi. Consultare la documentazione su un determinato servizio che viene 
fornito o utilizzato. 

Se si sta fornendo un nuovo servizio per un'applicazione che comunica con altri 
sistemi, il primo passo consiste nella progettazione del protocollo di comunicazione 
per i server e i client di questo servizio. Quali messaggi vengono trasmessi? Come 
vengono coordinati questi messaggi? Come sono codificate le informazioni? 

Comunicare con le applicazioni 

Spesso, l'applicazione server o client fornisce uno strato tra il software di rete e 
un'applicazione che usa il servizio. Un server HTTP, ad esempio, risiede tra Internet 
e un'applicazione server web che fornisce le pagine di contenuti e risponde ai 
messaggi di richiesta HTTP. 

I socket forniscono l'interfaccia tra l'applicazione server o client e il software di rete. 
Occorre fornire l'interfaccia tra la propria applicazione e i client che la utilizzano. E 
possibile copiare l'API di un server standard di terze parti (come ad esempio 
Apache) oppure si puo progettare e rendere pubblica la propria API. 

Servizi e porte 



La maggior parte dei servizi standard sono associati, per convenzione, con 
determinati numeri di porta. Parleremo dettagliatamente dei numeri di porta nelle 
pagine seguenti. Per il momento, si consideri il numero di porta come un codice 
numerico per il servizio. 

Se si sta implementando un servizio standard in applicazioni multipiattaforma, gli 
oggetti socket di Linux mettono a disposizione dei metodi che consentono di cercare 
il numero di porta del servizio. Se si sta fornendo un nuovo servizio, e possibile 
specificare il numero di porta associato nel file /etc/services. Per maggiori 
informazioni sul file services, consultare la documentazione di Linux. 

Tipi di connessioni socket 



Le connessioni socket possono essere divise in tre tipi fondamentali che indicano il 
modo in cui si e iniziata la connessione e a quale socket locale e connesso. Questi tipi 
sono 

• Connessioni client. 

• Connessioni di ascolto. 
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• Connessioni server. 

Una volta stabilita una connessione con un socket client, la connessione server e 
praticamente indistinguibile da una connessione client. Entrambi i punti terminali 
hanno le stesse funzionalita e ricevono gli stessi tipi di evento. Solo la connessione di 
ascolto e fondamentalmente dif ferente, in quanto possiede soltanto un singolo punto 
terminale. 

Connessioni client 



Le connessioni client connettono un socket client posto sul sistema locale con un 
socket server posto su un sistema remoto. Le connessioni client vengono iniziate dal 
socket client. Per prima cosa, il socket client deve descrivere il socket server a cui 
desidera connettersi. II socket client quindi cerca il socket server e, una volta 
localizzatolo, richiede una connessione. II socket server pud non completare la 
connessione immediatamente. I socket server conservano una coda di richieste client 
e completano le connessioni quando ne hanno il tempo. Quando il socket server 
accetta la connessione client, trasmette al socket client una descrizione completa del 
socket server al quale si sta connettendo e la connessione viene completata dal client. 

Connessioni di ascolto 



I socket server non localizzano i client. Formano invece "mezze connessioni" passive 
che ascoltano le richieste del client. I socket server associano una coda alle loro 
connessioni di ascolto; la coda registra le richieste di connessione client via via che 
queste vengono inoltrate. Quando il socket server accetta una richiesta di 
connessione dall'applicazione client, forma un nuovo socket per connettersi con 
client, cosi da lasciare la connessione di ascolto aperta per accettare altre richieste 
client. 

Connessioni server 



Nel momento in cui il socket di ascolto accetta una richiesta del client, il socket server 
forma le connessioni server. Quando il server accetta la connessione, il client riceve 
una descrizione del socket server che completa la connessione. La connessione viene 
stabilita quando il socket client riceve questa descrizione e completa la connessione. 

Descrizione dei socket 



I socket consentono a un'applicazione per rete di comunicare con gli altri sistemi 
della rete. Ciascun socket puo essere considerato come un punto terminale di una 
connessione in rete. Dispone di un indirizzo che specifica: 

• II sistema su cui e in esecuzione. 

• I tipi di interfacce che e in grado di capire. 
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• La porta utilizzata per la connessione. 

Per descrivere appieno una connessione socket occorre fornire gli indirizzi dei socket 
su entrambe le estremita della connessione. E possibile descrivere l'indirizzo di 
ciascun punto terminale del socket o indicandone l'indirizzo IP oppure l'host e il 
numero della porta. 

Prima di poter stabilire una connessione socket, e necessario descrivere 
completamente i socket costituenti i relativi punti terminali. Alcune informazioni 
sono reperibili dal sistema su cui e in esecuzione l'applicazione. Non e ad esempio 
necessario descrivere l'indirizzo IP locale di un socket client dato che questa 
informazione e disponibile da sistema operativo. 

Le informazioni che occorre fornire dipendono dal tipo di socket col quale si sta 
operando. I socket client devono descrivere il server con il quale vogliono 
connettersi. I socket server di ascolto devono descrivere la porta che rappresenta il 
servizio che forniscono. 

Descrizione deH'host 



L'host e il sistema che sta eseguendo l'applicazione contenente il socket. E possibile 
descrivere l'host di un socket fornendo il suo indirizzo IP, che e una stringa di 
quattro valori numerici (byte) nella notazione con punti standard di Internet, come 
ad esempio 

123.197.1.2 

Un singolo sistema puo supportare piu di un indirizzo IP. 

Gli indirizzi IP sono spesso difficili da ricordare e capita spesso di scriverli in modo 
non corretto. Un'alternativa e quella di usare il nome dell'host. I nomi di host sono 
alias dell'indirizzo IP che si vedono spesso negli Uniform Resource Locators (URL). 
Sono stringhe che contengono un nome di dominio e un servizio, quale ad esempio 

http://www.ASite.com 

La maggior parte delle Intranet forniscono nomi host per gli indirizzi IP dei sistemi in 
Internet. E possibile apprendere il nome dell'host associato a un qualsiasi indirizzo IP 
(nel caso esista) impartendo il seguente comando dalla riga comandi: 

ns lookup IPADDRESS 

in cui IPADDRESS e l'indirizzo IP a cui si e interessati. Se al proprio indirizzo IP 
locale non e associato un nome di host e si vuole averne uno, si deve contattare 
l'amministratore della rete. E comune per i computer fare riferimento a se stessi con il 
nome di localhost e con il numero IP 127.0.0.1. 

I socket server non hanno bisogno di specificare un host. L'indirizzo IP locale puo 
essere letto dal sistema. Se il sistema locale supporta piu di un indirizzo IP, i socket 
server ascolteranno le richieste client simultaneamente su tutti gli indirizzi IP. 
Quando un socket server accetta una connessione, il socket client f ornisce l'indirizzo 
IP remoto. 

I socket client devono specificare l'host remoto fornendone il nome oppure 
indicando l'indirizzo IP. 
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Scelta tra un nome di host e un indirizzo IP 

La maggior parte delle applicazioni usa il nome dell'host per specificare un sistema. I 
nomi di host sono piu facili da ricordare ed e piu facile controllare che siano stati 
scritti correttamente. Inoltre, i server possono modificare il sistema o l'indirizzo IP 
associati ad un particolare nome di host. L'uso di un nome di host permette al socket 
client di trovare il sito astratto rappresentato dal nome di host, anche quando e stato 
spostato ad un nuovo indirizzo IP. 

Se il nome di host e sconosciuto, il socket client deve specificare il sistema del server 
usando l'indirizzo IP. Specificare il sistema del server fornendo l'indirizzo IP 
consente di risparmiare tempo. Quando si fornisce il nome di host, prima di poter 
localizzare il sistema del server, il socket deve cercare l'indirizzo IP associato a quel 
nome. 

Uso delle porte 



Benche l'indirizzo IP fornisca informazioni sufficienti per trovare il sistema all'altro 
capo di una connessione socket, occorre comunque anche il numero di porta di quel 
sistema. Senza numeri di porta, un sistema potrebbe formare solo una singola 
connessione alia volta. I numeri di porta sono identificatori unici che consentono a un 
singolo sistema di ospitare simultaneamente piu connessioni, assegnando un numero 
di porta separato a ciascuna connessione. 

In precedenza abbiamo descritto i numeri di porta come codici numerici dei servizi 
implementati da applicazioni in rete. Questa, in realta, e solo una convenzione che 
permette alle connessioni di ascolto server di rendersi disponibili su un numero di 
porta fisso in modo da poter essere trovate dai socket client. I socket server ascoltano 
le richieste sul numero di porta associato al servizio che forniscono. Quando 
accettano una connessione con un socket client, creano una connessione socket 
separata che usa un numero di porta diverso e arbitrario. In questo modo, la 
connessione di ascolto puo continuare ad ascoltare le richieste sul numero di porta 
associato al servizio. 

I socket client usano un numero di porta locale arbitrario perche non devono essere 
trovati da nessun altro socket. Specificano il numero di porta del socket server col 
quale vogliono connettersi in modo da poter trovare l'applicazione server. Spesso, 
questo numero di porta viene specificato indirettamente chiamando il servizio 
desiderate 

Utilizzo dei componenti socket 



La pagina Internet della Component palette include tre componenti socket che 
permettono a un'applicazione di rete di formare connessioni con altre macchine e 
all'utente di leggere e scrivere informazioni su quella connessione. Questi 
componenti sono: 

• TcpServer 

• TcpCHent 
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• UdpSocket 

Associati con ciascuno di questi componenti socket ci sono gli oggetti socket, che 
rappresentano il punto terminale di una connessione socket in uso. I componenti 
socket usano gli oggetti socket per incapsulare le chiamate del socket server; pertanto 
l'applicazione non deve preoccuparsi dei dettagli necessari per stabilire la 
connessione o di gestire i messaggi del socket. 

Se si vogliono personalizzare i dettagli delle connessioni che i componenti socket 
creano per conto dell'utente, si possono usare le proprieta, gli eventi e i metodi degli 
oggetti socket. 

Ottenimento di informazioni sulla connessione 



Dopo avere completato la connessione con un socket client o server, per ottenere 
informazioni sulla connessione e possibile usare l'oggetto socket client o server 
associato al proprio componente socket. Usare le proprieta LocalHost e LocalPort per 
determinare l'indirizzo e il numero di porta usati dal socket client o server locale 
oppure usare le proprieta RemoteHost e RemotePort per determinare l'indirizzo e il 
numero di porta usati dal socket client o server remote Usare il metodo 
GetSocketAddr per generare un indirizzo di socket valido in base al nome dell 'host e al 
numero di porta. E possibile utilizzare il metodi LookupPort per individuare il 
numero di porta. Utilizzare il metodo LookupProtocol method to look up the protocol 
number. Use the LookupHostName per individuare il nome dell'hosto in base 
all'indirizzo IP della macchina host. 

Per controllare il traffico di rete in ingresso e in uscita dal socket utilizzare le 
proprieta BytesSent e BytesReceived. 

Utilizzo di socket client 



Per convertire l'applicazione in un client TCP/IP o UDP, occorre aggiungere un 
componente TcpClient o UdpSocket alia scheda o al modulo dati. I socket client 
permettono di specificare il socket server al quale ci si vuole connettere e il servizio 
che si vuole dal server. Una volta descritta la connessione desiderata, si puo usare il 
componente socket client per completare la connessione con il server. 

Ogni componente socket client usa un singolo oggetto socket client per rappresentare 
il punto terminale client di una connessione. 

Specifica del server desiderate 

I componenti socket client hanno alcune proprieta che permettono di specificare il 
sistema e la porta server a cui ci si vuole connettere. Utilizzare la proprieta 
RemoteHost per specificare il server host remoto in base al nome host o all'indirizzo 
IP. 

Oltre al sistema server, si deve specificare la porta del sistema server con il quale il 
socket client si connettera.E possibile utilizzare la proprieta RemotePort per 
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specificare il numero di porta del server in modo diretto oppure indirettamente 
indicando il nome del servizio di destinazione. 

Formazione della connessione 

Una volta impostate le proprieta del componente socket client in modo che 
descrivano il server con il quale ci si vuole connettere, e possibile formare la 
connessione durante l'esecuzione chiamando il metodo Open. Se si vuole che 
l'applicazione esegua automaticamente la connessione al momento dell'avvio, 
occorre, in fase di progetto, impostare la proprieta Active a true, usando l'Object 
Inspector. 

Ottenimento di informazioni sulla connessione 

Dopo avere completato la connessione con un socket server, per ottenere 
informazioni sulla connessione e possibile usare l'oggetto socket associato col 
componente socket client. Usare le proprieta LocalHost e LocalPort per determinare 
l'indirizzo e il numero di porta usati dai socket client e server per formare il punto 
terminale della connessione. Si puo usare la proprieta Handle per ottenere un handle 
alia connessione socket da usare con le chiamate socket. 

Chiusura della connessione 

Una volta terminato la comunicazione con un'applicazione server attraverso la 
connessione socket, si puo chiudere la connessione chiamando il metodo Close. La 
connessione puo essere chiusa anche da parte del server. Se cosi e, l'utente ne 
ricevera notifica in un evento OnDisconnect. 

Uso dei socket server 



Per convertire un'applicazione in un server IP occorre aggiungere un componente 
socket server (TcpServer o UdpSocket) alia scheda o al modulo dati. I socket server 
permettono di specificare il servizio che si sta fornendo o la porta che si vuole usare 
per ascoltare le richieste di client. Si puo usare il componente socket server per 
ascoltare e accettare le richieste di connessione provenienti da client. 

Ogni componente socket server usa un singolo oggetto socket server per 
rappresentare il punto terminale server in una connessione di ascolto. Usa anche un 
oggetto socket server client per il punto terminale server di ciascuna connessione 
attiva, accettata dal server, verso un socket client. 

Specifica della porta 

Prima che il socket server possa ascoltare le richieste provenienti da client, si deve 
specificare la porta dal quale il server le ascoltera. Si puo specificare questo porta 
usando la proprieta LocalPort. Se l'applicazione server corrente fornisce un servizio 
standard che, per convenzione, e associato a un numero di porta specifico, e anche 
possibile specificare il nome del servizio usando la proprieta LocalPort. E preferibile 
utilizzare il nome del servizio invece del numero di porta, perche e piu facile 
commettere errori di battitura quando si specifica il numero di porta. 
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Ascolto delle richieste provenienti da client 

Una volta impostato il numero di porta del componente socket del server, durante 
l'esecuzione e possibile formare una connessione di ascolto chiamando il metodo 
Open. Se si vuole che l'applicazione in uso esegua automaticamente la connessione di 
ascolto all'avvio, occorre, in fase di progetto, impostare la proprieta Active a true, 
usando l'Object Inspector. 

Connessione con i client 

Un socket server di ascolto accetta automaticamente le richieste di connessione 
provenienti da client, man mano che le riceve. Ogni volta che questo si verifica se ne 
ha notifica in un evento OnAccept. 

Chiusura delle connessioni server 

Quando si vuole chiudere la connessione di ascolto, occorre chiamare il metodo Close 
o impostare la proprieta Active a false. Questo chiude tutte le connessioni con 
applicazioni client aperte, annulla tutte le connessioni non accettate in corso, e poi 
chiude la connessione di ascolto in modo che il componente socket del server non 
possa piu accettare alcuna nuova connessione. 

Quando i client TCP chiudono le proprie singole connessioni al socket del server, si 
viene informati mediante un evento OnDisconnect. 

Risposta agli eventi socket 



Quando si scrivono applicazioni che utilizzano socket, e possibile scrivere sul socket 

leggere dal socket da un punto qualsiasi del programma. E possibile scrivere sul 
socket utilizzando nel programma i metodi SendBuf, SendStream, o Sendln dopo che il 
socket e stato aperto. E possibile leggere dal socket utilizzando metodi che hanno un 
nome analogo ReceiveBufe Receiveln. Gli eventi OnSend e OnReceive vengono 
innescati ogni volta che si scrive o si legge qualcosa dal socket. Possono essere 
utilizzati per operazioni di filtro. Ogni volta che si legge o si scrive, viene innescato 
un evento di lettura o di scrittura. 

1 socket client e i socket server generano entrambi eventi di errore quando ricevono 
messaggi di errore dalla connessione. 

I componenti socket ricevono inoltre due eventi durante l'apertura e il 
completamento di una connessione. Se l'applicazione ha l'esigenza di influenzare il 
modo in cui avviene l'apertura del socket e necessario usare i metodi SendBuf e 
ReceiveBufper rispondere a questi eventi del client o del server. 

Eventi di errore 



I socket client e server generano eventi di errore quando ricevono messaggi di errore 
dalla connessione. E possibile scrivere un gestore di evento OnError che risponda a 
questi messaggi di errore. Al gestore di evento vengono passate informazioni 
relativamente a 
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• Quale oggetto socket ha ricevuto la notifica dell'errore. 

• Cio che il socket stava cercando di fare quando si e verificato l'errore. 

• II codice di errore fornito dal messaggio di errore. 

E possibile rispondere all'errore nel gestore di evento e cambiare il codice di errore in 
per impedire al socket di sollevare un'eccezione. 

Eventi del client 



Quando un socket client apre una connessione, si verificano i seguenti eventi: 

• Viene impostato e inizializzato il socket per la notifica dell'evento. 

• Si verifica un evento OnCreateHandle dopo che il server e il socket server sono stati 
individuati. A questo punto, l'oggetto socket disponibile tramite la proprieta 
Handle puo fornire informazioni sul socket server o client che costituira l'altra 
estremita della connessione. Questa e la prima possibility per ottenere la porta 
effettivamente usata per la connessione, che puo differire dalla porta del socket di 
ascolto che ha accettato la connessione. 

• La richiesta di connessione viene accettata dal server e completata dal socket 
client. 

• Una volta stabilita la connessione, si verifica l'evento di notifica OnConnect. 

Eventi del server 



I componenti socket server permettono di stabilire due tipi di connessione: 
connessioni di ascolto e connessioni alle applicazioni client. II socket server riceve 
eventi durante la formazione di ciascuna di queste connessioni. 

Eventi durante I'ascolto 

Poco prima che venga formata la connessione di ascolto, si verifica l'evento 
OnListening. E possibile usare la sua proprieta Handle per apportare modifiche al 
socket prima che venga aperto per I'ascolto. Per esempio, se si vogliono limitare gli 
indirizzi IP che il server usa per I'ascolto, occorre farlo in un gestore di evento 
OnListening. 

Eventi con connessioni client 

Quando un socket server accetta una richiesta di connessione del client, si verificano i 
seguenti eventi: 

• Si verifica un evento OnAccept che passa il nuovo oggetto TTcpClient al gestore 
dell'evento. Questa e la prima occasione in cui e possibile usare le proprieta di 
TTcpClient per ottenere informazioni sul punto terminale server della connessione 
ad un client. 

• Se BlockMode e bmThreadBlocking si verifica un evento OnGetThread. Se si desidera 
utilizzare un proprio discendente custom di TServerSocketThread, e possibile 
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crearne uno in un gestore di evento OnGetThreaded esso sara utilizzato al posto di 
TServerSocketThread. Se si desidera eseguire una inizializzazione del thread, o 
effettuare una qualsiasi chiamata API al socket prima che il thread inizi a leggere o 
scrivere sulla connessione, usare anche in questi casi il gestore di evento 
OnGetThread. 

• II client completa la connessione e si verifica un evento OnAccept. Con un server 
non bloccante puo essere opportuno a questo punto iniziare la lettura o la scrittura 
sulla connessione socket 

Lettura e scrittura sulle connessioni socket 



La ragione per cui si stabiliscono connessioni socket con altre macchine e che in 
questo modo si ha la possibility di leggere o scrivere informazioni su quelle 
connessioni. II tipo di informazioni da leggere o da scrivere, o quando farlo, 
dipendono dal servizio associato alia connessione socket. 

La lettura e la scrittura sui socket possono verificarsi in modo asincrono, cosi da non 
bloccare l'esecuzione di altro codice sull'applicazione in rete. Questa connessione e 
chiamata non bloccante. E anche possibile formare connessioni bloccanti, in cui 
un'applicazione aspetta il termine della lettura o della scrittura prima di eseguire la 
linea di codice successiva. 

Connessioni non bloccanti 



Le connessioni non bloccanti leggono e scrivono in modo asincrono, in modo che il 
trasferimento di dati non blocchi l'esecuzione di altro codice nell'applicazione in rete. 
Per crere una connessione non bloccante per socket client o server, impostare la 
proprieta BIockMode a bmNonBlocking. 

Quando la connessione e non bloccante, gli eventi di lettura e scrittura informano il 
socket quando il socket all'altra estremita della connessione tenta di leggere o 
scrivere informazioni. 

Eventi di lettura e scrittura 

I socket non bloccanti generano eventi di lettura e scrittura quando tentano di leggere 
o scrivere sulla connessione. E possibile rispondere a queste notifiche nei gestori di 
evento OnReceive o OnSend. 

L'oggetto socket associato alia connessione socket viene fornito sotto forma di 
parametro ai gestori di evento di lettura e scrittura. Questo oggetto socket possiede 
una serie di metodi che consentono di leggere o di scrivere sulla connessione. 

Per leggere dalla connessione socket, utilizzare i metodi ReceiveBufo Receiveln. Per 
scrivere sulla connessione socket, utilizzare i metodi SendBuf, SendStream, o Sendln. 
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Connessioni bloccanti 



Quando la connessione e di tipo bloccante, il proprio socket deve iniziare a leggere o 
a scrivere sulla connessione. II socket non puo aspettare passivamente una notifica 
dalla connessione. Si usi un socket di tipo bloccante quando la propria estermita della 
connessione ha la responsabilita del momento in cui si verificano operazioni di 
lettura o di scrittura. 

Per socket client o server, impostare la proprieta BlockMode a bmBlocking per formare 
una connessione di tipo bloccante.A seconda di cio che fa l'applicazione client, e 
possibile creare un nuovo thread esecutivo per leggere o scrivere, in modo da 
permettere all'applicazione di continuare ad eseguire il codice su altri thread mentre 
aspetta che la lettura o la scrittura sulla connessione vengano completate. 

Per i socket server, impostare la proprieta BlockMode a bmBlocking o bmThreadBlocking 
per formare una connessione di tipo bloccante. Dato che, mentre il socket aspetta le 
informazioni da scrivere o leggere sulla connessione, le connessioni di tipo bloccante 
interrompono l'esecuzione di tutto il resto del codice, quando il BlockMode e 
bmThreadBlocking i componenti socket server generano sempre un nuovo thread 
esecutivo per ogni connessione client. Se BlockMode e impostata a bmBlocking 
l'esecuzione di programma viene bloccata finche non si stabilisce una nuova 
connessione. 
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Sviluppo di applicazioni COM 

I capitoli inclusi nella sezione "Sviluppo di applicazioni COM" presentano i concetti 
necessari per generare applicazioni basate su COM, fra cui i controller Automation, i 
server Automation, i controlli ActiveX e le applicazioni COM+. 

II supporto per i client COM e disponibile in tutte le versioni di C++Builder. Tuttavia, 
per creare i server, bisogna disporre della versione Professional o Enterprise. 
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Capitolo 




Panoramica sulle tecnologie COM 

C++Builder fornisce wizard e classi che facilitano 1'implementazione di applicazioni 
basate sul Component Object Model (COM) di Microsoft. Con questi wizard e 
possibile creare classi basate su COM e componenti da usare all'interno di 
applicazioni, oppure client o server COM che implementano oggetti COM, server 
Automation (inclusi gli Active Server Objects), controlli ActiveX o ActiveForms 
completamente funzionali. 

I componenti COM, come quelli sulle pagine ActiveX, COM+ e Servers della 
Component palette, non possono essere utilizzati nelle applicazioni CLX. Questa 
tecnologia e destinata al solo utilizzo in ambiente Windows e non e multipiattaforma. 

COM e un modello software a componenti, indipendente dal linguaggio, che 
consente l'interazione tra i componenti software e le applicazioni eseguiti su 
piattaforma Windows. L'aspetto chiave di COM e la sua capacita di consentire la 
comunicazione fra componenti, fra applicazioni e fra client e server tramite interfacce 
chiaramente definite. Le interfacce consentono ai client di chiedere a un componente 
COM quali funzioni supporta in esecuzione. Per dotare il componente di ulteriori 
funzioni, e sufficiente aggiungere una opportuna interfaccia. 

Le applicazioni possono accedere alle interfacce dei componenti COM, presenti sullo 
stesso computer su cui risiede l'applicazione o che esistono su un altro computer 
della rete, mediante un meccanismo detto Distributed COM (DCOM). Per maggiori 
informazioni sui client, sui server e sulle interfacce, consultare la sezione, "Parti di 
un'applicazione COM", a pagina 38-3. 

Questo capitolo fornisce una panoramica concettuale della tecnologia sulla quale i 
controlli Automation e ActiveX sono costruiti. Nei capitoli successivi vengono 
riportate informazioni dettagliate sulla creazione degli oggetti Automation e dei 
controlli ActiveX in C++Builder. 

COM come specifica e implementazione 

COM e al contempo una specifica e un'implementazione. Le specifiche COM 
definiscono le modalita per la creazione di oggetti e le modalita di comunicazione tra 
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oggetti. In base a tali specifiche, gli oggetti COM possono essere scritti i diversi 
linguaggi, funzionare in spazi di elaborazione differenti e su piattaforme diverse. 
Finche gli oggetti sono conformi alia specifica scritta, possono comunicare. Cio 
consente di integrare il codice preesistente, relativo per esempio a un componente, 
con nuovi componenti implementati nei linguaggi orientati agli oggetti. 

L'implementazione COM e inclusa nella libreria Win32, la quale fornisce numerosi 
servizi importanti che supportano le specifiche scritte. La libreria COM contiene una 
serie di interfacce standard, che definiscono la funzionalita centrale di un oggetto 
COM, e un piccolo set di funzioni API, progettate specificatamente per la creazione e 
la gestione degli oggetti COM. 

Quando in un'applicazione si usano i wizard e gli oggetti VCL di C++Builder, si 
utilizza l'implementazione di C++Builder per la specifica COM. Inoltre, C++Builder 
fornisce alcuni wrapper per i servizi COM per quelle funzionalita che non 
implementa direttamente (come gli Active Document). 

C++Builder implementa gli oggetti in base alle specifiche COM utilizzando la 
Microsoft Active Template Library (ATL), modificata per classi e macro. 

Estensioni COM 

Essendosi evoluto, COM si e esteso oltre i servizi COM. COM e la base di altre 
tecnologie, come Automation, controlli ActiveX, Active Documents e Active 
Directories. Per informazioni dettagliate sulle estensioni COM, consultare 
"Estensioni COM" a pagina 38-10. 

Inoltre, quando si lavora all'interno di vasti ambienti distribuiti, e possibile creare 
oggetti COM transazionali. Prima di Windows 2000, tali oggetti non facevano parte 
dell'architettura COM, ma piuttosto pensati per funzionare in ambiente Microsoft 
Transaction Server (MTS). Con l'avvento di Windows 2000, tale supporto e stato 
integrato in COM+. Gli oggetti transazionali sono descritti in dettaglio nel Capitolo 
44, "Creazione di oggetti MTS o COM+". 

C++Builder fornisce i wizard per implementare con facilita applicazioni che 
incorporano le tecnologie sopra menzionate. Per informazioni dettagliate, consultare 
il paragrafo "Implementazione di oggetti COM con i wizard" a pagina 38-20. 
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Quando si implementa un'applicazione COM, occorre fornire: 

Interfaccia COM II modo in cui un oggetto espone i suoi servizi all'esterno dei client. 

Un oggetto COM fomisce un'interfaccia per ciascun gruppo di 
metodi correlati e proprieta. Si noti che le proprieta COM non sono 
identiche alle proprieta degli oggetti della VCL. Le proprieta COM 
utilizzano sempre metodi di accesso in lettura e scrittura e non 
vengono dichiara utilizzando la parola chiave property. 

Server COM Un modulo (EXE, DLL o OCX) che contiene il codice per un 
oggetto COM. Le implementazioni dell'oggetto risiedono nei 
server. Un oggetto COM implementa una o piu interfacce. 

Client COM II codice che chiama le interfacce per ottenere i servizi richiesti dal 
server. I client sanno che cosa acquisire dal server (tramite 
l'interfaccia), ma non sanno come il server fornisce i servizi. 
C++Builder semplifica il processo di creazione di un client, 
consentendo l'installazione di server COM (come un documento 
Word o una presentazione PowerPoint) sotto forma di 
componenti. Cio consente di effettuare la connessione al server e di 
agganciarne gli eventi mediante l'Object Inspector. 



Interfacce COM 



I client COM comunicano con gli oggetti tramite interfacce COM. Le interfacce sono 
gruppi di routine correlate logicamente o semanticamente, che forniscono la 
comunicazione tra un provider di un servizio (oggetto server) e i suoi client. II modo 
standard per illustrare un'interfaccia COM e mostrato nella Figura 38.1: 

Figura 38.1 Un'interfaccia COM 
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Object 



Ad esempio, ogni oggetto COM deve implementare l'interfaccia base, IUnknozvn. 
Mediante una routine di nome Querylnterface in IUnknozvn, i client possono richiedere 
altre interfacce implementate dal server. 

Gli oggetti possono avere piu interfacce, ciascuna delle quali implementa una 
funzionalita diversa. Un'interfaccia fornisce un modo per trasmettere al client quale 
servizio fornisce, senza fornire i particolari dell'implementazione, ovvero come o 
dove l'oggetto fornisce questo servizio. 

Gli aspetti fondamentali delle interfacce COM sono i seguenti: 

• Una volta pubblicate, le interfacce sono immutabili, cioe non cambiano. E possibile 
fare affidamento su un'interfaccia per fornire uno specifico set di funzioni. 
Un'ulteriore funzionalita viene fornita da altre interfacce. 
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• Per convenzione, gli identificatori dell'interfaccia COM iniziano con una lettera 
maiuscola I, seguita poi da un nome simbolico che definisce l'interfaccia, come 
IMalloc o IPersist. 

• Le interfacce hanno un'identificazione univoca, chiamata Globally Unique 
Identifier (GUID), che e un numero a 128 bit generato in modo casuale. I GUID 
dell'interfaccia vengono chiamati Interface Identifiers (IID). Cio elimina i conflitti 
nei nomi tra versioni differenti di un prodotto o tra prodotti diversi. 

• Le interfacce sono indipendenti dal linguaggio. E possibile usare qualsiasi 
linguaggio per implementare un'interfaccia COM a condizione che supporti una 
struttura di puntatori e possa chiamare, in modo esplicito o implicito, una 
funzione tramite un puntatore. 

• Le interfacce non sono di per se oggetti; esse forniscono un modo per accedere ad 
un oggetto. Pertanto, i client non accedono direttamente ai dati, ma attraverso un 
puntatore di interfaccia. Windows 2000 aggiunge un'ulteriore strato di 
indirezione, noto come interceptor, grazie a cui fornisce funzioni COM+ come 
l'attivazione just-in-time e la centralizzazione degli oggetti. 

• Le interfacce sono sempre ereditate dall'interfaccia fondamentale, IUnknown. 

• Le interfacce possono essere reindirizzate da COM tramite i proxy per consentire 
chiamate al metodo dell'interfaccia per la comunicazione tra thread, processi e 
macchine collegate in rete, il tutto senza che gli oggetti client o server debbano 
preoccuparsi del reindirizzamento. Per ulteriori informazioni consultare il 
paragrafo , "Server in-process, out-of-process e remoti", a pagina 38-6. 

L'interfaccia COM fondamentale, IUnknown 

1 Tutti gli oggetti COM devono supportare l'interfaccia fondamentale, IUnknown, un 
typedefper il tipo interfacia di base {interface. IUnknown contiene le seguenti routine: 

Querylnterface Fornisce i puntatori alle altre interfacce supportate 

dall'oggetto. 

AddRef eRelease Semplici metodi di conteggio dei riferimenti che tengono la 

traccia della durata dell'oggetto in modo che un oggetto possa 
cancellarsi quando il client non ha piu bisogno del suo 
servizio. 

Tramite il metodo Querylnterface di IUnknown, i client ottengono i puntatori ad altre 
interfacce. Querylnterface conosce le interfacce dell'oggetto server e pud dare ad un 
client un puntatore all'interfaccia richiesta. Ricevendo un puntatore ad 
un'interfaccia, il client e certo di poter chiamare qualsiasi metodo dell'interfaccia. 

Gli oggetti registrano la propria durata tramite i metodi di IUnknown, AddRef e 
Release, che sono dei semplici metodi di conteggio di riferimento. Finche il conteggio 
di riferimento dell'oggetto e diverso da zero, l'oggetto rimane in memoria. Quando il 
conteggio di riferimento raggiunge lo zero, l'implementazione dell'interfaccia puo 
disporre in modo sicuro degli oggetti sottostanti. 
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Puntatori di interfaccia COM 

Un puntatore di interfaccia e un puntatore a un'istanza di un oggetto che punta, a sua 
volta, aH'implementazione di ciascun metodo nell'interfaccia. L'implementazione e 
accessibile tramite un array di puntatori a questi metodi, chiamato vtable. Le vtable 
sono simili al meccanismo utilizzato per supportare le funzioni virtuali in C++. 
Grazie a questa somiglianza, il compilatore e in grado di risolvere le chiamate ai 
metodi nell'interfaccia con lo stesso criterio utilizzato per risolvere le chiamate ai 
metodi nelle classi C++. 

La vtable viene condivisa tra tutte le istanze di una classe di oggetti, cosicche per 
ciascuna istanza dell'oggetto, il codice oggetto alloca una seconda struttura che 
contiene i suoi dati privati. II puntatore di interfaccia del client, quindi, e un 
puntatore al puntatore a vtable, come mostrato nel seguente diagramma. 

Figura 38.2 Vtable dell'interfaccia 
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In Windows 2000 e nelle successive versioni di Windows, quando un oggetto e in 
esecuzione in ambiente COM+, viene fornito un livello aggiunto di indirezione tra il 
puntatore aU'interfaccia e il puntatore a vtable. II puntatore all' interfaccia 
disponibile per il client punta a un interceptor, il quale a sua volta punta a vtable. 
Questo permette a COM+ di fornire servizi come l'attivazione just-in-time, per cui il 
server puo essere disattivato e riattivato dinamicamente in un modo non visibile al 
client. Per ottenere cio, COM+ garantisce che l'interceptor si comporti come se fosse 
un nor male puntatore a vtable. 

Server COM 



Un server COM e un'applicazione o una libreria che fornisce servizi ad 
un'applicazione client o a una libreria. Un server COM e costituito da uno o piu 
oggetti COM, dove un oggetto COM e un insieme di proprieta (membri dati o 
contenuto) e di metodi (o funzioni membro). 

I client non sanno come un oggetto COM esegue il suo servizio; l'implementazione 
dell'oggetto rimane incapsulata. Un oggetto rende disponibili i suoi servizi tramite le 
sue interfacce, come descritto precedentemente. 

Inoltre, i client non hanno bisogno di sapere dove risiede un oggetto COM. COM 
fornisce l'accesso trasparente che non tiene conto della dislocazione dell'oggetto. 
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Quando un client richiede un servizio da un oggetto COM, il client passa un 
identificatore di classe (CLSID) a COM. Un CLSID e semplicemente un GUID che 
identifica un oggetto COM. COM utilizza questo CLSID, memorizzato nel file di 
registro di sistema, per individuare l'apposita implementazione del server. Una volta 
individuato il server, COM porta il codice in memoria e fa in modo che il server crei 
un'istanza dell'oggetto per il client. Questo processo e gestito in modo indiretto 
tramite un oggetto speciale detto class factory o "fabbrica di classi" (basato sulle 
interfacce) che crea su richiesta istanze di oggetti. 

In sostanza, un server COM deve: 

• Registrare le voci nel registro di sistema che associano il modulo del server 
all'identificatore di classe (CLSID). 

• Implementare un oggetto class factory, che costruisca un altro oggetto di un 
particolare CLSID. 

• Esporre l'oggetto class factory a COM. 

• Fornire un meccanismo di scaricamento tramite il quale un server che non sta 
fornendo servizi ai client possa essere rimosso dalla memoria. 

I wizard di C++Builder automatizzano la creazione di oggetti e di server COM, come 
descritto nel paragrafo "Implementazione di oggetti COM con i wizard" a 
pagina 38-20. 

CoClass e class factory 

Un oggetto COM e un'istanza di una CoClass, che e una classe che implementa una o 
piu interfacce COM. L'oggetto COM fornisce i servizi come definiti dalle sue 
interfacce. 

Le CoClass vengono istanziate da uno speciale tipo di oggetto chiamato class factory. 
Ogni qualvolta i servizi di un oggetto vengono richiesti da un client, un class factory 
crea e registra un'istanza dell'oggetto per quel particolare client. Normalmente, se un 
altro client richiede i servizi dell'oggetto, il class factory crea un'altra istanza 
dell'oggetto per fornire il servizio al secondo client. (I client possono anche eseguire il 
bind ad oggetti COM in esecuzione, i quali si registrano al fine di poterli supportare.) 

Una CoClass deve avere un class factory e un identificatore di classe (CLSID), in 
modo che possa essere istanziato esternamente, cioe, da un altro modulo. L'uso di 
questi particolari identificatori per le CoClass ne rende possibile l'aggiornamento 
ogni volta che le nuove interfacce vengono implementate nella loro classe. Una 
nuova interfaccia puo modificare o aggiungere metodi senza influenzare le versioni 
piu vecchie, il che e un problema comune quando si usano le DLL. 

I wizard di C++Builder si occupano dell'assegnazione degli identificatori di classe, 
deU'implementazione e dell'istanziazione dei class factory. 

Server in-process, out-of-process e remoti 

Con COM un client non ha bisogno di conoscere dove risiede un oggetto; 
semplicemente effettua una chiamata ad un'interfaccia dell'oggetto. COM compie i 
passi necessari per effettuare la chiamata. Questi sono diversi a seconda del fatto che 
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l'oggetto risieda nello stesso processo del client, in un altro processo nella macchina 
client o in un'altra macchina della rete. I diversi tipi di server sono conosciuti come: 



Server in-process 



Una libreria (DLL) che viene eseguita nello stesso spazio di 
processo del client, ad esempio, un controllo ActiveX 
incorporato in una pagina Web visualizzata in Internet 
Explorer o Netscape. II controllo ActiveX viene, cioe, prelevato 
nella macchina client e richiamato all'interno dello stesso 
processo del browser Web. 

II client comunica con il server in-process usando chiamate 
dirette aU'interfaccia COM. 

Un'altra applicazione (EXE) in esecuzione in un differente spazio 
di processo, ma sulla sfessa macchina del client. Per esempio, un 
f oglio elettronico Excel incorporato in un documento di Word 
sono due applicazioni separate in esecuzione sulla stessa 
macchina. 

II server locale utilizza COM per comunicare con il client. 

Una DLL o un'altra applicazione in esecuzione su una macchina 
diversa da quella del client. Per esempio, un'applicazione 
database C++Builder, collegata ad un application server su 
un'altra macchina della rete. 

II server remoto usa interfacce COM (DCOM) distribuite per 
accedere e comunicare con l'application server. 

Come mostrato nella Figura 38.3, per i server in-process i puntatori alle interfacce 
dell'oggetto sono nello stesso spazio di processo del client, quindi COM effettua 
chiamate dirette all'implementazione dell'oggetto. 

Figura 38.3 Server in-process 
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Cio non e sempre vero in ambiente COM+. Quando un client effettua una chiamata a 
un oggetto in un contesto differente, COM+ intercetta la chiamata, facendo cosi in 
modo che essa si comporti come una chiamata a un server out-of-process (vedere piu 
avanti) anche se il server e in-process. Per maggiori informazioni sulle operazioni con 
COM+, consultare il Capitolo 44, "Creazione di oggetti MTS o COM+". 

Come mostrato nella Figura 38.4, quando il processo si trova in un processo o in una 
macchina diversi, COM usa un proxy per iniziare le chiamate della procedura 
remota. II proxy risiede nello stesso processo del client, quindi dal punto di vista del 
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client, tutte le chiamate all'interfaccia sembrano uguali. II proxy intercetta la 
chiamata del client e la inoltra nel punto in cui l'oggetto vero e proprio e in 
esecuzione. II meccanismo che consente al client di accedere agli oggetti in uno 
spazio di processo diverso, o anche in una macchina diversa, come se fossero nel 
proprio processo, e detto marshaling (smistamento. 

Figura 38.4 Server out-of-process e remoti 
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La differenza tra i server out-of-process e quelli remoti sta nel tipo di comunicazione 
usata dai processi. II proxy usa COM per comunicare con un server out-of-process e 
le interfacce COM (DCOM) distribuite per comunicare con una macchina remota. 
DCOM trasferisce, in modo del tutto trasparente, una richiesta di un oggetto locale 
ad un oggetto remoto in esecuzione su una macchina differente. 

Per le chiamate a procedure remote, DCOM utilizza il protocollo RPC fornito da 
Open Group's Distributed Computing Environment (DCE). Per la sicurezza 
distribuita, DCOM utilizza il protocollo di sicurezza di NT LAN Manager (NTLM). 
Per i servizi delle directory, DCOM utilizza il Domain Name System (DNS). 

II meccanismo di smistamento 

Lo smistamento e il meccanismo che consente ad un client di effettuare chiamate alle 
funzioni di interfaccia per oggetti remoti in un altro processo o su una macchina 
differente. Lo smistamento 

• Prende un puntatore di interfaccia nel processo del server e rende disponibile un 
puntatore proxy al codice del processo del client. 

• Trasferisce gli argomenti di una chiamata all'interfaccia come passati dal client e li 
colloca nello spazio di processo dell'oggetto remoto. 

Per qualsiasi chiamata all'interfaccia, il client mette gli argomenti in uno stack ed 
effettua una chiamata di funzione tramite il puntatore di interfaccia. Se la chiamata 
all'oggetto non e in-process, questa viene passata al proxy. II proxy chiude gli 
argomenti in un pacchetto di smistamento e trasmette la struttura all'oggetto remoto. 
Lo stub dell'oggetto apre il pacchetto, mette gli argomenti nello stack e chiama 



38-8 Guida alia programmazione 



Parti di un'applicazione COM 



l'implementazione dell'oggetto. In sintesi, l'oggetto ricrea la chiamata del client nel 
suo stesso spazio di indirizzo. 

II tipo di smistamento che si verifica dipende da quale interfaccia l'oggetto COM 
implementa. Gli oggetti possono usare un meccanismo di smistamento standard 
fomito dall'interfaccia IDispatch. Questo e un meccanismo di smistamento generico, 
che consente la comunicazione tramite una chiamata alia procedura remota tipica del 
sistema (RPC). Per informazioni dettagliate suU'interfaccia IDispatch, consultare il 
paragrafo "Interfacce di Automation" a pagina 41-13. Anche se l'oggetto non 
implementa IDispatch, se si limita a tipi compatibili con automation e possiede una 
libreria di tipi registrata, COM e in grado di fornire automaticamente il supporto per 
lo smistamento. 

Le applicazioni che non si limitano ai tipi compatibili con automation o che non 
registrano una libreria di tipi devono prowedere al proprio smistamento. Lo 
smistamento viene fomito o attraverso un'implementazione dell'interfaccia IMarshal, 
o utilizzando una DLL proxy /stub generata separatamente. C++Builder non 
supporta la generazione automatica di DLL proxy/ stub. 

Aggregazione 

A volte, un oggetto server utilizza un altro oggetto COM per compiere alcune 
funzioni. Per esempio, un oggetto gestione magazzino potrebbe fare uso di un 
oggetto fattura separato per gestire le fatture dei clienti. Se l'oggetto gestione 
magazzino desiderasse presentare l'interfaccia fattura ai client, ci sarebbe tuttavia un 
problema: Sebbene un client dotato dell'interfaccia magazzino possa chiamare 
Querylnterface per ottenere l'interfaccia fattura, al momento della creazione 
dell'oggetto fattura non sapeva niente dell'oggetto gestione magazzino e non puo 
restituire un'interfaccia magazzino in risposta ad una chiamata a Querylnterface. Un 
client che ha l'interfaccia fattura non puo rimettersi in contatto con l'interfaccia 
magazzino. 

Per evitare questo problema, alcuni oggetti COM supportano l'aggregazione. 
Quando l'oggetto gestione magazzino crea un'istanza dell'oggetto fattura, gli passa 
una copia della propria interfaccia IUnknown. L'oggetto fattura puo utilizzare quindi 
quella interfaccia IUnknown per gestire tutte le chiamate a Querylnterface che 
richiedono un'interfaccia, come l'interfaccia magazzino che egli non supporta. 
Quando accade cio, i due oggetti insieme sono definiti un aggregato. L'oggetto 
fattura e detto oggetto interno, oppure oggetto contenuto dell'aggregato, e l'oggetto 
magazzino e detto oggetto esterno. 

Per comportarsi come l'oggetto esterno di un aggregato, un oggetto COM deve 
creare l'oggetto interno utilizzando le funzioni CoCreatelnstance o CoCreatelnstanceEx 
delle API di Windows, passando il suo puntatore IUnknown come parametro che 
l'oggetto interno potra utilizzare per chiamate Querylnterface. A questo scopo, e 
anche possibile creare un'istanza di un oggetto TComlnterface e utilizzarne il metodo 
Createlnstance. 

Gli oggetti che si comportano come oggetto interno di un aggregato mettono a 
disposizione due implementazioni dell'interfaccia IUnknown: una che rimanda le 
chiamate Querylnterface che non e in grado di gestire all'interfaccia di controllo 
IUnknown dell'oggetto esterno, e una che restituisce un errore quando riceve 
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chiamate Querylnterface che non e i grado di gestire. I wizard di C++Builder creano 
automaticamente oggetti che includono questo supporto per il comportamento da 
oggetti interni. 

Client COM 



I client sempre possono interrogare le interfacce di un oggetto COM per determinare 
cosa e i grado di fornire. Tutti gli oggetti COM consentono ai client di richiedere le 
interfacce note. Inoltre, se il server supporta l'interfaccia IDispatch, i client possono 
interrogare il server per ricevere informazioni sui metodi supportati dall'interfaccia. 
Gli oggetti server non possono fare previsioni sull'utilizzo dei propri oggetti da parte 
dei client. Analogamente, i client non hanno bisogno di sapere come (ne tantomeno 
dove) tin oggetto fornisce i servizi; semplicemente si affidano agli oggetti server per 
fornire i servizi che reclamizzano tramite le proprie interfacce. 

Esistono due tipi di client COM, controller e contenitori. I controller lanciano il server 
e interagiscono con esso tramite la sua interfaccia. Richiedono servizi dall'oggetto 
COM oppure lo pilotano come processo separato. I contenitori ospitano i controlli 
visuali o gli oggetti che appaiono nell'interfaccia utente del contenitore. Utilizzano 
interfacce predefinite per trattare le questioni di visualizzazione con gli oggetti 
server. E impossibile avere una relazione di contenitori su DCOM; ad esempio, i 
controlli visuali che appaiono nell'interfaccia utente del contenitore devono essere 
situati localmente. Cio e dovuto al fatto che ci si aspetta che i controlli si traccino da 
soli, il che richiede che abbiano accesso a risorse GDI locali. 

C++Builder semplifica lo sviluppo di client COM consentendo l'importazione di una 
libreria di tipi o di un controllo ActiveX in un componente wrapper, in modo che 
l'oggetto server assomigli agli altri componenti della VCL. Per maggiori informazioni 
su questo processo, consul tare Capitolo 40, "Creazione di client COM". 

Estensioni COM 



Originariamente COM e stato progettato per fornire una funzionalita centrale di 
comunicazione e per consentirne l'ampliamento tramite le estensioni. COM ha esteso 
poi la sua funzionalita centrale definendo set specialistici di interfacce per scopi 
specifici. 
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Controlli ActiveX 



Active Server Pages 



L'elenco seguente riporta alcune delle estensioni dei servizi COM forniti attualmente. 
Le sezioni successive descrivono questi servizi piu in dettaglio. 

Server Automation Automation si riferisce alia possibility di un'applicazione di 
controllare da programma gli oggetti di un'altra 
applicazione. Gli Automation server sono oggetti che 
possono essere controllati da altri eseguibili in fase di 
esecuzione. 

I controlli ActiveX sono server in-process specializzati, 
progettati solitamente per essere incorporati in 
un'applicazione client. I controlli mettono a disposizione sia 
eventi sia comportamenti in esecuzione e in progettazione. 

Active Server Pages sono script che generano pagine HTML. 
Questo linguaggio di scripting include costrutti per la 
creazione e l'esecuzione di oggetti Automation. Cio significa 
che Active Server Page si comportano come un Automation 
controller. 

Sono oggetti che supportano il collegamento e 
l'incorporamento, operazioni di drag-and-drop, l'editing 
visuale e l'attivazione in loco. I documenti di Word e i fogli 
elettronici di Excel sono esempi di Active Document. 

Oggetti che includono un supporto supplementare per 
rispondere a un vasto numero di client. Questo supporto 
include funzioni quali attivazione just-in-time, transazioni, 
centralizzazione di risorse e servizi di sicurezza. In origine 
queste funzioni erano gestite da MTS ma, con l'awento di 
COM+, sono state incorporate in COM. 

Oggetti che supportano il modello a eventi con associazione 
flessibile di COM+. A differenza del modello con 
associazione rigida usato dai controlli ActiveX, II modello a 
eventi di COM+ consente di sviluppare publisher di eventi 
in modo indipendente dai subscriber di eventi. 

Una raccolta di strutture di dati statiche, spesso salvata come 
risorsa, che fornisce informazioni di tipo dettagliate su un 
oggetto e sulle sue interfacce. I client degli Automation 
server, dei controlli ActiveX e degli oggetti transazionali si 
aspettano che le informazioni di tipo siano disponibili. 

II seguente diagramma illustra la relazione delle estensioni COM e il modo in cui 
sono costruite in COM: 



Active Documents 



Oggetti transazionali 
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e subscription di 
evento 



Librerie di tipi 



Panoramica sulle tecnologie COM 38-11 



Estensioni COM 

Figura 38.5 Tecnologie basate su COM 
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Gli oggetti COM possono essere visuali o non visuali. Alcuni devono essere eseguiti 
nello stesso spazio di processo dei rispettivi client; altri possono essere eseguiti in 
processi differenti o in macchine remote, purche gli oggetti forniscano il supporto per 
lo smistamento. La Tabella 38.1 riassume i tipi di oggetti COM che e possibile creare, 
indica se sono visuali o meno, gli spazi di processo in cui possono essere eseguiti, 
come provvedono alio smistamento e se richiedono o meno una libreria di tipi. 

Tabella 38.1 Requisiti degli oggetti COM 
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Server Automation 



Automation si riferisce alia possibility di un'applicazione di controllare da 
programma gli oggetti di un'altra applicazione, come una macro che puo manipolare 
piu di un'applicazione contemporaneamente. L'oggetto server da manipolare viene 
chiamato oggetto Automation, mentre II client di un oggetto Automation viene 
definito come Automation controller. 

L'oggetto Automation puo essere usato su server in-process, locali e remoti. 
L'oggetto Automation e caratterizzato fondamentalmente da due aspetti: 

• Definisce un set di proprieta e comandi e descrive le loro capacita attraverso le 
descrizioni di tipo. Per ottenere cio, occorre trovare il modo di fornire 
informazioni sulle interfacce, sui metodi di interfaccia e sugli argomenti di questi 
metodi. Normalmente queste informazioni sono disponibili in una libreria di tipi. 
Automation server puo generare anche informazioni di tipo dinamico, quando 
interrogato tramite la sua interfaccia IDispatch (vedere di seguito). 

• Rende i metodi accessibili in modo che le altre applicazioni possano usarli. Per 
questo, implementa l'interfaccia IDispatch. Tramite questa interfaccia un oggetto 
puo esporre tutti i suoi metodi e tutte le sue proprieta. Tramite il metodo 
principale di questa interfaccia e possibile richiamare i metodi dell'oggetto, dopo 
che sono stati identificati attraverso le informazioni di tipo. 

Spesso gli sviluppatori utilizzano Automation per creare e utilizzare oggetti OLE non 
visuali che vengono eseguiti in tutti gli spazi di processo perche l'interfaccia 
IDispatch di Automation rende automatico il processo di smistamento. Automation, 
comunque, limita i tipi che e possibile utilizzare. 

Per un elenco dei tipi che risultano validi per le librerie di tipi in generale, e per le 
interfacce Automation in particolare, consultare "Tipi consentiti" a pagina 39-12. 

Per informazioni sulla scrittura di un Automation server, consultare il Capitolo 41, 
"Creazione di semplici server COM". 
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La tecnologia Active Server Page (ASP) consente di scrivere semplici programmi 
detti Active Server Pages che possono essere avviati dai client tramite un server web. 
A differenza dei controlli ActiveX che vengono eseguiti sui client, le Active Server 
Page sono eseguite sul server, e restituiscono come risultato ai client una pagina 
HTML. 

Le Active Server Pages sono scritte in Jscript o in VB script. Lo script viene eseguito 
ogni volta che il server carica la pagina Web. Questi script possono avviare a loro 
volta un Automation server incorporato (o un Enterprise Java Bean). Per esempio, e 
possibile scrivere un Automation server, ad esempio per creare una bitmap o per 
eseguire una connessione a un database, e questo server accede ai dati che vengono 
aggiornati ogni qualvolta il client carica la pagina del Web. 

Active Server Pages si basano sull'ambiente Microsoft Internet Information Server 
(IIS) per servire le pagine Web. 

I wizard di C++Builder permettono di creare un Active Server Object, che e un 
oggetto Automation espressamente progetto per operare con un Active Server Page. 
Per maggiori informazioni sulla creazione e l'utilizzo di questi tipi di oggetti, 
consultare il Chapter 42, "Creazione di Active Server Page". 

Controlli ActiveX 



ActiveX e una tecnologia che consente di ottenere componenti COM, in particolar 
modo i controlli, piu compatti ed efficienti. Questa caratteristica e particolarmente 
necessaria per quei controlli che si prevede dovranno essere utilizzati in applicazioni 
Intranet e che i client devono necessariamente scaricare prima di poterli utilizzare. 

I controlli ActiveX sono controlli visuali che vengono eseguito solo come server in- 
process, e possono essere inglobati in un'applicazione contenitore di tipo controllo 
ActiveX. Essi non sono di per se applicazioni complete, ma possono essere pensati 
come controlli OLE prefabbricati riutilizzabili in varie applicazioni. I controlli 
ActiveX hanno un'interfaccia utente visibile e devono appoggiarsi a interfacce 
predefinite per concordare le modalita di I/O e di visualizzazione con i contenitori 
che li ospitano. 

I controlli ActiveX fanno uso di Automation per esporre le loro proprieta, i loro 
metodi e i loro eventi. Le funzionalita dei controlli ActiveX includono la possibility di 
attivare gli eventi, di collegarsi alle sorgenti di dati e di supportare la concessione 
delle licenze. 

Un uso dei controlli ActiveX e nei siti Web come oggetti interattivi di una pagina 
Web. Proprio per questo, ActiveX e diventato uno standard, destinato a contenuti 
interattivi per il World Wide Web, compreso l'uso degli ActiveX Document per la 
visualizzazione di documenti non HTML tramite un browser Web. Per ulteriori 
informazioni sulla tecnologia ActiveX, visitare il sito Web ActiveX di Microsoft. 



38-14 Guida alia programmazione 



Estensioni COM 



I wizard di C++Builder consentono di creare con facilita controlli ActiveX. Per 
ulteriori informazioni sulla creazione e sull'uso di questi tipi di oggetti, consultare il 
Capitolo 43, "Creazione di un controllo ActiveX". 

Active Documents 



Gli Active Document (precedentemente definiti documenti OLE) costituiscono un set 
di servizi COM, che supportano il collegamento e l'incorporamento, il drag-and- 
drop, e l'editing visuale. Gli Active Document possono incorporare agevolmente dati 
o oggetti di formati differenti, quali clip sonore, spreadsheets, testo e bitmap. 

A differenza dei controlli ActiveX, gli Active Document non sono limitati ai server in- 
process; possono essere usati anche in applicazioni cross-process. 

A differenza degli oggetti Automation, che raramente sono visuali, gli oggetti Active 
Document possono essere attivi in modo visuale in un'altra applicazione. Pertanto, 
essi vengono associati a due tipi di dati: i dati di presentazione, usati per visualizzare 
l'oggetto su un monitor o su un dispositivo di output, e i dati nativi, usati per 
modificare un oggetto. 

Gli oggetti Active Document possono essere contenitori o server di documenti. 
Anche se C++Builder non fornisce un wizard automatico per la creazione di Active 
Document, si puo usare la classe VCL, TOleContainer, per supportare il collegamento 
e l'incorporamento degli Active Document esistenti. 

E anche possibile usare TOleContainer come base per un contenitore Active 
Document. Per creare oggetti per i server Active Document, si deve usare il COM 
object wizard e aggiungere le interfacce appropriate, a seconda dei servizi che 
l'oggetto ha bisogno di supportare. Per ulteriori informazioni sulla creazione e 
sull'uso dei server Active Document, visitare il sito Web ActiveX di Microsoft. 

Anche se la specifica di Active Document incorpora il supporto per lo smistamento 
relativamente alle applicazioni cross-process, gli Active Document non vengono 
eseguiti sui server remoti, poiche usano tipi specifici di un sistema su una 
determinata macchina come handle di finestre, handle di menu, e cosi via. 

Oggetti transazionali 



C++Builder utilizza il termine "oggetti transazionali" per fare riferimento a oggetti 
che sfruttano i servizi per le transazioni, la sicurezza e la gestione delle risorse forniti 
da Microsoft Transaction Server (MTS) (per le versioni di Windows precedenti a 
Windows 2000) o da COM+ (per Windows 2000 e successive). Questi oggetti sono 
progettati per operare in vasti ambienti distribuiti. 

I servizi per le transazione forniscono la solidita, garantendo sempre il 
completamento delle attivita o il ritorno alia stato di origine (il server non compie 
mai un'attivita solo parzialmente). I servizi per la sicurezza consentono di esporre 
diversi livelli di supporto a classi diverse di client. La gestione delle risorse consente 
ad un oggetto di gestire piu client unendo le risorse o mantenendo attivi gli oggetti 
soltanto quando sono utilizzati. Per consentire al sistema di fornire questi servizi, 
l'oggetto deve implementare l'interfaccia IObjectControl. Per accedere ai servizi, gli 
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oggetti transazionali usano un'interfaccia di nome IObjectControl creata per loro 
conto da MTS o da COM+ . 

In ambiente MTS, l'oggetto server deve essere incorporate in una libreria (DLL) che 
va quindi installata nell'ambiente di esecuzione di MTS. Ovvero, l'oggetto server e 
un server in-process che viene eseguito nel spazio del processo di esecuzione di MTS. 
In ambiente COM+, questa restrizione non esiste in quanto tutte le chiamate COM 
vengono indirizzate tramite un inter cettatore. Dal punto di vista dei client, la 
differenza tra MTS e COM+ e inesistente. 

I server MTS o COM+ raggruppano oggetti transazionali che vengono eseguiti nello 
stesso spazio di processo. In ambiente MTS, questo gruppo e definito un package 
MTS, mentre in ambiente COM+ e definito un'applicazione COM+. Una singola 
macchina pud eseguire molti package MTS (o applicazioni COM+) diversi, dove 
ciascuno di essi viene eseguito in un spazio di processo separato. 

Dal punto di vista dei client, l'oggetto transazionale puo apparire come qualsiasi 
altro oggetto server COM. II client non dovra mai sapere nulla sulle transazioni, sulla 
sicurezza oppure sull'attivazione just-in-time, a meno che non stia iniziando una 
transazione per suo conto. 

MTS e COM+ forniscono entrambi un strumento separato per amministrare gli 
oggetti transazionali. Questo strumento consente di configurare oggetti in package o 
applicazioni COM+, vedere package o applicazioni COM+ installate su un computer, 
vedere o modificare gli attributi degli oggetti inclusi, esaminare e gestire transazioni, 
rendere disponibili oggetti a client, e cosi via. In ambiente MTS, questo strumento e 
MTS Explorer. In ambiente COM+ e il COM+ Component Manager. 

Oggetti evento COM+ e subscriber di eventi 



II sistema a eventi di COM+ introduce uno strato di software intermedio che separa 
le applicazioni che generano eventi (chiamate publisher) dalle applicazioni che 
rispondono agli eventi (dette subscriber). Invece di essere rigidamente collegati gli 
uni agli altri, i publisher e i subscriber possono essere sviluppati, distribuiti e attivati 
indipendentemente l'uno dall'altro. 

Nel modello a eventi di COM+, viene creata per prima cosa un'interfaccia di evento 
utilizzando COM+ Event Object wizard di C++Builder's. L'interfaccia di evento non 
ha alcuna implementazione; semplicemente definisce i metodi dell'evento che i 
publisher genereranno e a cui i subscriber risponderanno. L'oggetto evento COM+ 
viene quindi installato in una COM+ Application, nel COM+ Catalog. L'operazione 
puo essere condotta utilizzando TIDE di C++Builder, da programma utilizzando 
l'oggetto TComAdminCatalog o da un un amministratore di sistema utilizzando lo 
strumento Component Services. 

I subscriber di eventi sono responsabili della fornitura di un'implementazione per 
l'interfaccia dell'evento. E possibile creare componenti subscriber di eventi 
utilizzando COM+ Event Subscription wizard di C++Builder. Utilizzando il wizard, 
e possibile selezionare l'oggetto evento che si desidera implementare e C++Builder 
preparera il modello di tutti i metodi dell'interfaccia. Nel caso l'oggetti evento non 
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sia stato ancora installato nel COM+ Catalog, e possibile anche selezionare una 
libreria di tipi. 

Infine, una volta implementato il componente subscriber, lo si deve anche installare 
nel COM+ Catalog. Ancora una volta, l'operazione pud essere condotta mediante 
1'IDE di C++Builder, mediante un oggetto TComAdminCatalog oppure utilizzando lo 
strumento amministrativo Component Services. 

Quando un publisher desidera generare un evento, crea semplicemente un'istanza 
dell'oggetto evento (non il componente subscriber) e chiama i metodi appropriati 
dell'interfaccia dell'evento. A questo punto interviene COM+ e lo notifica a tutte le 
applicazioni che sono abbonate a quell'oggetto evento, chiamandole in modo 
sincrono una alia volta. In questo modo, i subscriber non devono avere alcuna 
informazione sulle applicazioni che si abbonano all'evento. Ai subscriber non serve 
nient'altro che un'implementazione dell'interfaccia dell'evento e non deveono far 
altro che selezionare quei publisher a cui desiderano abbonarsi. Tutto il resto viene 
gestito da COM+. 

Per maggiori informazioni sulla generazione di eventi COM+, vedere "Generazione 
di eventi in ambiente COM+" a pagina 44-22. 

Librerie di tipi 



Le librerie di tipi forniscono un modo per ottenere ulteriori informazioni di tipo su 
un oggetto che pud essere determinato dall'interfaccia di un oggetto. Le informazioni 
di tipo contenute nelle librerie di tipi forniscono i dati necessari sugli oggetti e sulle 
loro interfacce, comunicando, per esempio, quali interfacce esistono nei diversi 
oggetti (dato il CLSID), quali funzioni membro esistono in ciascuna interfaccia e quali 
argomenti richiedono tali funzioni. 

E possibile ottenere informazioni di tipo sottoponendo a query un'istanza in 
esecuzione di un oggetto o caricando e leggendo le librerie di tipi. Con queste 
informazioni si pud implementare un client per l'uso di un oggetto desiderata, 
sapendo specificamente quali funzioni membro occorrono, e che cosa passare loro. 

I client degli Automation server, dei controlli ActiveX e degli oggetti transazionali si 
aspettano che le informazioni di tipo siano disponibili. Tutti wizard di C++Builder 
generano automaticamente una libreria di tipi. E possibile visualizzare o modificare 
queste informazioni di tipo usando il Type Library Editor, come descritto nel 
Capitolo 39, "Funzionamento delle librerie di tipi". 

Questa sezione descrive che cosa contiene una libreria di tipi, come viene creata, 
quando viene usata e come vi si puo accedere. Per gli sviluppatori che vogliono 
condividere le interfacce tra piu linguaggi, la sezione termina con suggerimenti 
sull'uso degli strumenti della libreria di tipi. 

Contenuto delle librerie di tipi 

Le librerie di tipo contengono informazioni di tipo, che indicano quali interfacce 
esistono nei diversi oggetti COM, e i tipi e il numero degli argomenti per i metodi di 
interfaccia. Queste descrizioni includono identificatori univoci per le CoClass 
(CLSID) e per le interfacce (IID), in modo che vi si possa accedere in modo corretto, 
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nonche gli identificatori dispatch (dispID) per i metodi e le proprieta dell'interfaccia 
Automation. 

Le librerie di tipi possono contenere anche le seguenti informazioni: 

• Descrizione di informazioni personalizzate di tipo associate alle interfacce 
personalizzate 

• Routine che vengono esportate dal server Automation o ActiveX, ma che non sono 
metodi di interfaccia 

• Informazioni sulle enumerazioni, sui record (strutture), sulle unioni, sugli alias e 
sui tipi di dati del modulo 

• Riferimenti alle descrizioni di tipo da altre librerie di tipo 

Creazione di librerie di tipi 

Con i tradizionali strumenti di sviluppo si possono creare librerie di tipi scrivendo 
script nell'Interface Definition Language (IDL) o nell'Object Description Language 
(ODL), quindi eseguendo lo script tramite un compilatore. Comunque, C++Builder 
genera automaticamente una libreria di tipi quando si crea un oggetto COM (inclusi 
controlli ActiveX, oggetti Automation, moduli dati remoti e cosi via) usando uno dei 
wizard presenti sulla pagina ActiveX o Multitier della finestra di dialogo New Items. 
E possibile creare una libreria di tipi anche scegliendo dal menu principale il 
comando File I New I Other, quindi selezionando la pagina ActiveX e quindi 
selezionando Type Library. 

Per visualizzare la libreria di tipi, si pud usare il Type Library editor di C++Builder. 
Una libreria di tipi puo essere facilmente modificata usando il Type Library editor; 
C++Builder aggiorna automaticamente il file .tbl corrispondente (binary type library 
file) nel momento in cui si salva la libreria di tipi. Se si apportano modifiche alle 
Interfaces e alle CoClasses create utilizzando un wizard, il Type Library editor 
aggiorna anche i file di implementazione. Per maggiori informazioni sull'utilizzo del 
Type Library editor per scrivere interfacce e CoClasses, consultare il Capitolo 39, 
"Funzionamento delle librerie di tipi". 

Quando usare le librerie di tipi 

E importante creare una libreria di tipi per ogni insieme di oggetti che viene esposto 
agli utenti esterni, 

• I controlli ActiveX richiedono una libreria di tipi, che deve essere inclusa come 
risorsa nella DLL che contiene i controlli ActiveX. 

• Gli oggetti esposti che supportano il binding tramite vtable delle interfacce 
personalizzate devono essere descritti in una libreria di tipi, in quanto i riferimenti 
vtable vengono inglobati in fase di compilazione. I client importano le 
informazioni sulle interfacce dalla libreria di tipi e usano tali informazioni per la 
compilazione. Per ulteriori informazioni sui binding di vtable e su quello in fase di 
compilazione, consultare "Interfacce di Automation" a pagina 41-13. 

• Le applicazioni che implementano gli Automation server devono fornire una 
libreria di tipi, in modo che i client vi si possano collegare anticipatamente. 
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• Gli oggetti istanziati dalle classi che supportano l'interfaccia IProvideClassInfo, 
devono avere una libreria di tipi. 

• Le librerie di tipi non sono indispensabili, ma sono comunque utili per 
l'identificazione degli oggetti usati con OLE drag-and-drop. 

Accesso alle librerie di tipi 

La libreria binaria di tipi fa normalmente parte di un file di risorse (.res) o di un file 
indipendente con estensione .tlb. Se e inclusa in un file di risorse, la libreria di tipi 
puo essere incorporata in un server (.dll, .ocx o .exe). 

Una volta creata una libreria di tipi, i browser dell'oggetto, i compilatori e gli altri 
strumenti simili possono accedervi tramite speciali interfacce di tipo: 



Interfaccia 


Descrizione 


ITypeLib 


Fornisce i metodi per accedere alle descrizioni di una liberia di 
tipi. 

Potenzia ITypeLib in modo da includere il supporto per stringhe 
di documentazione, dati custom e dati statistici sulla libreria di 
tipi. 

Fornisce le descrizioni dei singoli oggetti contenuti in una 
libreria di tipi. Per esempio, un browser usa questa interfaccia 
per estrarre le informazioni sugli oggetti dalla libreria di tipi. 


ITypeLM 


ITypelnfo 


ITypeInfo2 


Potenzia ITypelnfo in modo da accedere ad altre informazioni 
sulla libreria di tipi, inclusi i metodi per accedere ad elementi 
dati custom. 


ITypeComp 


Fornisce un modo rapido per accedere alle informazioni che 
servono al compilatore per il collegamento ad un'interfaccia. 



C++Builder e in grado di importare e usare librerie di tipi da altre applicazioni 
scegliendo il comando Project I Import Type Library. 



Vantaggi dell'uso delle librerie di tipi 

Anche se un'applicazione non richiede una libreria di tipi, si possono sempre 
prendere in considerazione i vantaggi che derivano dal suo uso: 

• E possibile usare il binding anticipato con Automation (anziche la chiamata 
tramite i Variant), mentre i controller che non supportano vtable o le interfacce 
duali possono inserire i dispID nel codice in fase di compilazione, migliorando le 
prestazioni in fase di esecuzione. 

• I browser di tipo possono analizzare la libreria, in modo che i client possano 
vedere le caratteristiche degli oggetti. 

• Si puo usare la funzione RegisterTypeLib per registrare gli oggetti esposti nel 
database di registrazione. 

• Si puo usare la funzione UnRegisterTypeLib per disinstallare completamente una 
libreria di tipi dell'applicazione dal registro di sistema. 
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• L'accesso al server locale viene migliorato, in quanto Automation usa le 
informazioni della libreria di tipi per inglobare i parametri che vengono passati ad 
un oggetto in un altro processo. 

Uso degli strumenti della libreria di tipi 

Qui di seguito sono elencati gli strumenti per lavorare con le librerie di tipi. 

• Lo strumento TLIBIMP (Type Library Import), che prende le librerie di tipi 
esistenti e crea i file C++Builder Interface (file _TLB.cpp e _TLB.h), e incluso nel 
Type Library editor. TLIBIMP offre altre opzioni di configurazione che non sono 
disponibili nel Type Library editor. 

• TRegSvr e uno strumento per la registrazione e la rimozione dei server e delle 
librerie di tipi, che viene fornito con C++Builder. II file sorgente di TRegSvr e 
disponibile come esempio nella directory Examples. 

• II compilatore Microsoft IDL (MIDL) compila gli script IDL per creare una libreria 
di tipi. MIDL ha un'opzione facoltativa per la generazione di file header, trovata in 
MS Win32 SDK. 

• RegSvr32.exe, uno strumento per la registrazione e la rimozione dei server e delle 
librerie di tipi, e un programma di utilita standard di Windows. 

• OLEView OLEView e uno strumento browser della libreria di tipi, disponibile nel 
sito Web di Microsoft. 

Implementazione di oggetti COM con i wizard 



C++Builder semplifica enormemente la scrittura di applicazioni server COM poiche 
include diversi wizard in grado di gestire la maggior parte dei dettagli. C++Builder 
mette a disposizione wizard distinti per creare: 

• Un semplice oggetto COM 

• Un oggetto Automation 

• Un Active Server Object (per l'incorporazione in una Active Server page) 

• Un controllo ActiveX 

• Una scheda ActiveX 

• Un oggetto transazionale 

• Un oggetto COM+ Event 

• Un oggetto COM+ Subscription Event 

• Una pagina di proprieta 

• Una libreria di tipi 

• Una libreria ActiveX 

I wizard gestiscono la maggior parte delle operazioni connesse alia creazione di 
qualunque tipo di oggetto COM. Forniscono le interfacce COM necessarie per 
ciascun tipo di oggetto. Come mostrato nella Figura 38.6, con un semplice oggetto 
COM il wizard implementa l'interfaccia COM IUnknown necessaria, che fornisce un 
puntatore di interfaccia all'oggetto. 
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Figura 38.6 Una semplice interfacia per un oggetto COM 

lUnknown i 1 



COM 
Object 



II COM object wizard fornisce anche una implementazione per IDispatch nel caso si 
specifichi che si sta creando un oggetto che supporta un discendente di IDispatch. 

Come mostrato nella Figura 38.7, per gli oggetti Automation e Active Server, il 
wizard implementa lUnknown e IDispatch, che forniscono lo smistamento automatico. 

Figura 38.7 Interfaccia di un oggetto Automation 

lUnknown 



IDispatch 



Automation 
Object 



ACome mostrato nella Figura 38.8, per gli oggetti del controllo ActiveX e schede 
ActiveX il wizard implementa tutte le necessarie interfacce del controllo ActiveX, 
lUnknown, IDispatch, lOleObject, lOleControl, e cosi via. 

Figura 38.8 Interfaccia di un oggetto ActiveX 
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La Tabella 38.2 elenca i vari wizard e le interfacce da essi implementate: 



Tabella 38.2 Wizard di C++Builder per I'implementazione di oggetti COM, Automation e ActiveX 



Wizard 

COM server 



Interfacce implementate Che cosa fa il wizard 



IUnknown (e IDispatch se si 
seleziona un'interfaccia 
predefinita che deriva da 
IDispatch) 



Esporta le routine per gestire la registrazione 
del server, la registrazione della classe, il 
caricamento e lo scaricamento del server, e 
l'istanziazione di un oggetto. 

Crea e gestisce le class factory per gli oggetti 
implementati nel server. 

Prepara gli elementi del file di registro per 
quegli oggetti che specificano il modello di 
threading selezionato. 

Offre il supporto lato-server per la generazione 
di eventi, se necessario. 

Dichiara i metodi che implementano una 
interfaccia selezionata, e preparando la 
struttura base delle implementazioni che il 
programmatore dovra poi completare. 
Fornisce una libreria di tipi. 

Permette di selezionare un'interfaccia 
arbitraria, registrata nella libreria di tipi, e di 
implementarla. Se lo si fa, e necessario 
utilizzare una libreria di tipi. 



Automation 
server 



Active Server 
Object 



ActiveX Control 



IUnknown, IDispatch 



IUnknown, IDispatch, 
(IASPObject) 



IUnknown, IDispatch, 

IPersistStreamlnit, 

IOlelnPlaceActiveObject, 

IPersistStorage, IViewObject, 

IOleObject, IViewObject!, 

lOleControl, 

IPerPropertyBrowsing, 

IOlelnPlaceObject, 

ISpecifyPropertyPages 



Esegue le funzioni di un wizard per server 
COM (descritto in precedenza), e inoltre: 

Implementa l'interfaccia specificata, duale o 
dispatch. 

Esegue le funzioni di un wizard per oggetti 
Automation (descritto in precedenza) e genera 
facoltativamente una pagina .ASP che puo 
essere caricata in un browser Web. Lascia 
aperto il Type Library editor per consentire, se 
occorre, la modifica delle proprieta dell'oggetto 
e dei metodi. 

Mette a disposizione le caratteristiche 
intrinseche di ASP sotto forma di proprieta in 
modo da semplificare il reperimento delle 
informazioni relative all'applicazione ASP e ai 
messaggi HTTP che l'hanno avviata. 

Esegue le funzioni del wizard per Automation 
server (descritti in precedenza), e inoltre: 

Genera una CoClass di implementazione che 
corrisponde al controllo della VCL su cui e 
basato il controllo ActiveX e che implementa 
tutte le interfacce ActiveX. 

Lascia aperto l'editor del codice sorgente in 
modo che si possa modificare la classe di 
implementazione. 
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Tabella 38.2 Wizard di C++Builder per I'implementazione di oggetti COM, Automation e ActiveX (continua) 



Wizard 

ActiveForm 



Transactional 
object 



COM+ Event 
object 



COM+ 

Subscription 

object 

Type Library 
ActiveX library 



Interfacce implementate Che cosa fa il wizard 



Stesse interfacce di ActiveX 
Control 



IUnknown, IDispatch, 
IObjectControl 



Property Page IUnknown, IPropertyPage 



Nessuna, per impostazione 
predefinita 



Nessuna, per impostazione 
predefinitadefault 

Nessuna, per impostazione 
predefinita 

Nessuna, per impostazione 
predefinita 



Esegue le funzioni del wizard per controlli 
ActiveX, e inoltre: 

Crea un discendente di TActiveForm che 
sostituisce la classe VCL preesistente nel 
wizard ActiveX control. Questa nuova classe 
consente di progettare la Active Form con le 
stesse modalita usate per progettare una 
scheda in una applicazione Windows. 

Aggiunge al progetto corrente una nuova unit 
che contiene la definizione dell'oggetto MTS o 
COM+. Inserisce nella libreria di tipi GUID 
proprietari in modo che C++Builder possa 
installare correttamente l'oggetto, lasciando 
aperto il Type Library editor per consentire la 
definizione delle interfacce che l'oggetto 
espone ai client. L'oggetto deve essere 
installato separatamente dopo averlo generato. 

Crea una nuova pagina di proprieta che e 
possibile progettare nel Forms designer. 

Crea un oggetto evento COM+ che e possibile 
definire usando il Type Library editor. A 
differenza dei wizard per gli altri oggetti, 
COM+ Event object wizard non crea una unit 
di implementazione in quanto gli oggetti 
evento non hanno implementazione (che e 
fornita dall'oggetto subscriber dell'evento). 

Crea un oggetto subscriber COM+ che 
implementa l'interfaccia di evento scelta. 

Crea una nuova libreria di tipi e la associa al 
progetto attivo. 

Crea un nuovo ActiveX o server Com DLL ed 
espone le necessarie funzioni di esportazione. 



E possibile aggiungere altri oggetti COM o reimplementare una loro 
implementazione esistente. Per aggiungere un nuovo oggetto, la cosa piu semplice e 
utilizzare nuovamente un wizard. Questo perche il wizard imposta un'associazione 
fra la libreria di tipi e una classe di implementazione, in modo che le modifiche 
apportate alia libreria di tipi vengano applicate automaticamente all'oggetto di 
implementazione. 



Codice generato dai wizard 



I wizard di C++Builder generano codice che utilizza il linguaggio ATL (Active 
Template Library) di Microsoft come base per il supporto COM. ATL e un 
framework di classi modello che gestiscono parecchi dettagli implementativi dello 
sviluppo di applicazioni COM.Poiche ATL si basa su modelli, non e possibile 
eseguire il link in DLL. II progetto includera, invece, i file header di ATL che saranno 
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compilati in codice oggetto. I wizard di C++Builder generano le istruzioni include 
per questi file header in una unit con suffisso _ATL (Per esempio, Projectl_ATL.cpp e 
Projectl_ATL.h). 




I file header ATL presenti nella directory Include/ ATL di C++Builder differiscono 
leggermente dai file header di ATL forniti da Microsoft. Queste differenze sono 



necessarie affinche il compilatore di C++Builder possa compilare gli header. Non e 
possibile sostituire questi header con un'altra versione di ATL, pena la non corretta 
compilazione. 

Oltre alle istruzioni include per i file ATL (e per i file aggiuntivi che consentono alle 
classi ATL di operare con le classi VCL), lo header della unit _ATL generato include 
anche la dichiarazione di una variabile globale di nome _Module. _Module e 
un'istanza della classe ATL CComModule che isola il resto dell'applicazione dalle 
differenze tra DLL e EXE nel modo in cui sono gestiti gli aspetti relativi al threading e 
alia registrazione. Nel file di progetto (Projectl.cpp), _Module viene assegnata a 
un'istanza di TComModule, un discendente di CComModule che supporta To stile di 
C++Builder per la registrazione di COM. Di solito, non sara necessario utilizzare 
direttamente questo oggetto. 

II wizard aggiunge al file di progetto anche una mappa di oggetti. Questa e una serie 
di macro ATL che assomigliano a quanto segue: 

BEGIN_OBJECT_MAP ( Ob] ectMap ) 

OBJECT_ENTRY (CLSID_MyObj , TMyObjlmpl) 
END_OBJECT_MAP ( ) 

Ogni elemento tra le linee BEGIN_OBJECT_MAP e END_OBJECT_MAP definisce 
un'associazione tra un ID di classe e la sua classe di implementazione ATL. L'oggetto 
_Module usa questa mappa per registrare i componenti. La mappa di oggetti e 
utilizzata anche dalle classi creatore di oggetti ATL. Se si aggiunge all'applicazione 
un qualsiasi oggetto COM senza l'aiuto di un wizard, si dovra aggiornare la mappa 
degli oggetto affinche possano essere registrati e creati nel corretto. Per fare cio, 
aggiungere un'altra linea che utilizzi la macro OBJECT_ENTRY, assegnando come 
parametri 1TD di classe e il nome della classe di implementazione. 

I wizard generano una unit di implementazione per il particolare tipo di oggetto 
COM che si sta creando. L'unit di implementazione contiene la dichiarazione della 
classe che implementa l'oggetto COM. Questa classe e un discendente (diretto o 
indiretto) della classe ATL CComObjectRootEx, della classe ATL CComCoClass, e di 
altre classi che dipendono dal tipo di oggetto che si sta creando. 

CComCoClass fornisce il supporto class factory necessario per la creazione della 
classe. Utilizza la mappa di oggetti che era stata aggiunta al file di progetto. 

CComObjectRootEx e una classe modello che fornisce il supporto necessario per 
IUnknown. Essa implementa il metodo Querylnterface facendo uso di una mappa di 
interfacce che e possibile trovare nell'header della unit di implementazione. La 
mappa di interfacce assomiglia a quanto segue: 

BEGIN_COM_MAP ( TMyOb] Impl ) 

COM_INTERFACE_ENTRY ( IMyObj ) 
END_COM_MAP ( ) 
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Ogni elemento nella mappa di interfacce e un'interfaccia che viene esposta dal 
metodo Querylnterface. Se si aggiungono alia classe di implementazione ulteriori 
interfacce, sara necessario aggiungerle alia mappa di interfacce (utilizzando la macro 
COM_INTERFACE_ENTRY), e aggiungerle come altri antenati della classe di 
implementazione. 

CComObjectRootEx fornisce il supporto necessario per il conteggio dei riferimenti. 
Tuttavia, non dichiara i metodi AddRefe Release. Questi metodi vengono aggiunti alia 
classe di implementazione tramite la macro END_COM_MAP() alia fine della mappa 
di interfacce. 

Per maggiori informazioni su ATL, consultare la documentazione di Microsoft. Si 
noti, comunque, che il supporto COM di C++Builder non utilizza ATL per la 
registrazione, per i controlli ActiveX (che sono invece basati su oggetti della VCL), o 
per il supporto di pagina di proprieta. 

I wizard generano anche una libreria di tipi e la relativa unit associata, il cui nome 
assume il formato Projectl_TLB.La unit Projectl_TLB include le definizioni che 
l'applicazione ha bisogno di utilizzare, le definizioni di tipo e le interfacce definite 
nella libreria di tipi. Per maggiori informazioni sui contenuti di questo file, consultare 
"Codice generato durante l'importazione delle informazioni di una libreria di tipi" a 
pagina 40-5. 

E possibile modificare l'interfaccia generata dal wizard utilizzando il Type Library 
editor. Se si apportano modifiche, la classe di implementazione viene 
automaticamente aggiornata in modo da tener conto di tali modifiche. Per 
completare l'implementazione, sara necessario solamente completare il corpo dei 
metodi generati. 
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Funzionamento delle 



librerie di tipi 



Questo capitolo descrive come creare e modificare le librerie di tipi usando l'editor di 
Type Library di C++Builder. Le librerie di tipi sono file che includono informazioni 
sui tipi di dati, sulle interfacce, sulle funzioni membro e sulle classi di oggetti esposte 
da un oggetto COM. Le librerie di tipi forniscono un modo per identificare quali tipi 
di oggetti e di interfacce sono disponibili su un server. Per una panoramica 
dettagliata sul perche e su quando usare le librerie di tipi, consultare "Librerie di 
tipi" a pagina 38-17. 

Una libreria di tipi puo contenere: 

• Informazioni sui tipi di dati personalizzati come gli alias, gli enumerativi, le 
strutture e le union. 

• Descrizioni su uno o piu elementi COM, come un'interfaccia, dispinterface, o una 
CoClass. A ciascuna di queste descrizioni viene generalmente fatto riferimento 
come informazioni di type. 

• Descrizioni delle costanti e dei metodi definiti in moduli esterni. 

• Riferimenti alle descrizioni di tipo di altre librerie di tipi. 

Includendo una libreria di tipi con l'applicazione COM o con la libreria ActiveX, si 
rendono disponibili le informazioni sugli oggetti dell'applicazione ad altre 
applicazioni e ad altri strumenti di programmazione tramite gli strumenti per le 
librerie di tipi e le interfacce di COM. 

Con i tradizionali strumenti di sviluppo, e possibile preparare librerie di tipi creando 
script in IDL (Interface Definition Language), quindi eseguendoli tramite un 
compilatore. II Type Library editor automatizza alcuni di questi processi, rendendo 
molto meno complessa ed onerosa la creazione di proprie librerie di tipi. 

Quando si crea un server COM di qualsiasi tipo (controllo ActiveX, oggetto 
Automation, modulo dati remoto e cosi via) utilizzando i wizard di C++Builder, il 
wizard genera automaticamente una libreria di tipi. La maggior parte del lavoro che 
si fa per personalizzare l'oggetto generato inizia con la libreria di tipi, poiche e in essa 
che si definiscono le proprieta e i metodi che la libreria espone ai client: si modifica 
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l'interfaccia della CoClass generata dal wizard utilizzando il Type Library editor. II 
Type Library editor aggiorna automaticamente la unit di implementazione 
dell'oggetto, e tutto cio che si dovra fare sara completare il corp dei metodi generati. 



Type Library editor 



II Type Library editor e uno strumento che consente agli sviluppatori di esaminare e 
di creare informazioni di tipo per gli oggetti COM. L'utilizzo del Type Library editor 
puo semplificare enormemente lo sviluppo di oggetti COM centralizzando la 
definizione di interfacce, CoClasses, e tipi, l'ottenimento dei GUID per le nuove 
interfacce, l'associazione di interfacce alle CoClasses, l'aggiornamento della unit di 
implementazione e cosi via. 

II Type Library editor genera due tipi di file che rappresentano i contenuti della 
libreria di tipi: 

Tabella 39.1 File di Type Library editor 
File Descrizione 

.TLB file II file binario della libreria di tipi. Per impostazione predefinita, non sara necessario 
utilizzare questo file, poiche la libreria di tipi viene compilata automaticamente 
nell'applicazione come risorsa. Comunque, sara possibile utilizzare questo file per 
compilare esplicitamente la libreria di tipi in un altro progetto o per distribuire 
separatamente la libreria di tipi dall'EXE o dall'OCX. Per maggiori informazioni, 
consultare "Apertura di una libreria di tipi esistente" a pagina 39-14 and 
"Distribuzione delle librerie di tipi" a pagina 39-20. 



TLB unit Questa unit (file .cpp e .h) interpreta i contenuti della libreria di tipi per l'uso 

nell'applicazione. Contiene tutte le dichiarazioni che occorrono all'applicazione per 
utilizzare gli elementi definiti nella libreria di tipi. Sebbene sia possibile aprire 
questo file nel Code editor, non lo si dovra mai modificare — la manutenzione e 
affidata al Type Library editor, e pertanto tutte le modifiche apportate saranno 
sovrascritte dal Type Library editor. Per maggiori informazioni sui contenuti di 
questo file, consultare "Codice generato durante 1'importazione delle informazioni 
di una libreria di tipi" a pagina 40-5. 
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Gli elementi principali del Type Library editor sono elencati nella Tabella 39.2: 



Tabella 39.2 Parti di Type Library editor 
Parte Descrizione 



Barra strumenti 



Pannello Object 
list 

Barra di stato 



Pagine 



Include pulsanti per aggiungere alia libreria di tipi nuovi tipi, CoClass, 
interfacce e membri dell'interfaccia. La barra strumenti include anche pulsanti 
per aggiornare la unit di implementazione, registrare la libreria di tipi, e 
salvare un file IDL contenente le informazioni incluse nella libreria di tipi. 

Mostra tutti gli elementi esistenti nella libreria di tipi. Quando si fa clic su uno 
degli elementi nel pannello, vengono visualizzate la pagine valide relative a 
quell'oggetto. 

Visualizza gli errori di sintassi se si cerca di aggiungere tipi non validi alia 
libreria di tipi. 

Visualizzano informazioni sull'oggetto selezionato. Le pagine visualizzate 
dipendono dal tipo di oggetto selezionato. 



Tali parti sono illustrate nella Figura 39.1, che mostra il Type Library editor che 
visualizza le informazioni di tipo per un oggetto COM di nome eye. 

Figura 39.1 Type Library editor 
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Barra strumenti 

La barra strumenti del Type Library editor, posizionata nella parte superiore del 
Type Library editor, contiene i pulsanti che e possibile selezionare per aggiungere 
alia libreria di tipi nuovi oggetti. 

II primo gruppo di pulsanti consente di aggiungere elementi alia libreria di tipi. Se si 
fa clic su un pulsante della barra strumenti, nel pannello Object list appaiono le icone 
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relative a quel certo elemento. E possibile personalizzarne gli attributi utilizzando il 
pannello di destra. A seconda dell'icona selezionata, sulla destra appaiono pagine di 
informazioni differenti. 

La tabella seguente elenca gli elementi che e possibile aggiungere alia libreria di tipi: 





Una descrizione di interfaccia. 




Una descrizione di dispinterface. 




Una CoClass. 




Una enumerazione. 




Un alias. 




Un record. 




Una union. 




Un modulo. 



Quando si seleziona nel pannello Object list uno degli elementi elencati in 
precedenza, il secondo gruppo di pulsanti visualizza i membri che risultano validi 
per quel certo elemento. Per esempio, quando si seleziona Interface, le icone Method 
e Property nel secondo riquadro diventano attive poiche e possibile aggiungere alia 
definizione di interfaccia metodi e proprieta. Quando si seleziona Enum, il secondo 
gruppo di pulsanti cambia per visualizzare il membro Const, che e l'unico membro 
valido per le informazioni di tipo Enum. 

La tabella seguente elenca i membri che e possibile aggiungere agli elementi nel 
pannello Object list 



Un metodo dell'interfaccia, della dispinterface o un entry point in un modulo. 
Una proprieta di un'interfaccia o di una dispinterface. 

Una proprieta a sola scrittura. (disponibile dall'elenco a discesa sul pulsante della 
proprieta) 

Una proprieta in lettura /scrittura. (disponibile dall'elenco a discesa sul pulsante della 
proprieta) 

Una proprieta a sola lettura. (disponibile dall'elenco a discesa 
sul pulsante della proprieta) 
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Un campo in un record o in una union. 
♦ Una costante in una enumerazione o in un modulo. 



Nel terzo riquadro e possibile aggiornare, registrare o esportare la propria libreria di 
tipi (salvandola come file IDL) come descritto nel paragrafo "Salvataggio e 
registrazione delle informazioni della libreria di tipi" a pagina 39-19. 

Pannello Object list 

II pannello Object list mostra tutti gli elementi della libreria di tipi attiva utilizzando 
una vista ad albero. La radice dell'albero rappresenta la libreria ed e rappresentata 
con la seguente icona: 




Dal nodo della libreria di tipi si diramano verso il basso gli elementi inclusi nella 
libreria di tipi: 

Figura 39.2 Pannello Object list 
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Quando si seleziona uno di questi elementi (incluso la stessa libreria di tipi), le 
pagine relative alle informazioni di tipo riportate alia destra si modificano riportando 
solo le informazioni pertinenti per quel certo elemento. E possibile utilizzare queste 
pagine per modificare la definizione e le proprieta dell'elemento scelto. 

E possibile intervenire sugli elementi nel pannello Object list facendo clic destro in 
modo da richiamare il menu contestuale. In questo menu sono inclusi comandi che 
permettono di utilizzare gli Appunti di Windows per spostare o copiare gli elementi 
esistenti, oltre a comandi per aggiungere nuovi elementi o per personalizzare 
l'aspetto del Type Library editor. 

Barra di stato 

Quando si effettua l'editing o il salvataggio di una libreria di tipi, la sintassi, gli errori 
di traduzione e i messaggi di segnalazione vengono elencati nel pannello Status. 

Per esempio, se si specifica un tipo IDL non supportato dal Type Library editor, viene 
visualizzato un errore di sintassi. Per un elenco completo dei tipi supportati dal type 
Library editor, consultare "Tipi consentiti" a pagina 39-12. 
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Pagine di informazioni di tipo 

Quando si seleziona un elemento nel pannello Object list, nel Type Library editor 
appaiono le pagine di informazioni di tipo che sono valide per l'elemento 
selezionato. Quali pagine appariranno dipende dall'elemento selezionato nel 
pannello Object list: 

Tabella 39.3 Pagine del Type Library editor 

Pagina di 
Elemento informazione di 
Type Info tipo 



Type library Attributes 
Uses 
Flags 
Text 

Interface Attributes 

Flags 
Text 

Dispinterface Attributes 
Flags 
Text 

CoClass Attributes 
Implements 
COM+ 

Flags 

Text 

Enumeration Attributes 
Text 



Contenuto della pagina 

Nome, versione e GUID della libreria di tipi, oltre a 
informazioni per il collegamento alia Guida. 

Elenco di altre librerie di tipi che contengono definizioni da 
cui questa libreria dipende. 

Flag che determinano come le altre applicazioni possono 
utilizzare la libreria di tipi. 

Tutte le definizioni e le dichiarazioni che definiscono la 
libreria di tipi in oggetto (vedere di seguito). 

Denominate, versione e GUID dell'interfaccia, il nome 
dell'interfaccia da cui deriva, e informazioni utili per il link 
dell'interfaccia. 

Flag che indicano se l'interfaccia e nascosta, duale, 
compatibile con Automation e/o estensibile. 

Le definizioni e le dichiarazioni per lTnterface (trattatta nel 
prosieguo del capitolo). 

Nome, versione e GUID dell'interfaccia, e informazioni per il 
collegamento alia Guida. 

Flag che indicano se la Dispinterface e nascosta, duale, e/ o 
estensibile. 

Le definizioni e le dichiarazioni della Dispinterface. (vedere 
di seguito). 

Nome, versione e GUID della CoClass e informazioni per il 
collegamento alia Guida. 

Un elenco di interfacce implementate dalla CoClass e dei 
rispettivi attributi. 

Gli attributi di oggetti transazionali, come il modello della 
transazione, la sincronizzazione delle chiamate, l'attivazione 
just-in-time, la centralizzazione di oggetti e cosi via. Include 
anche gli attributi degli oggetti evento di COM+. 

Flag che indicano i vari attributi della CoClass, incluso come i 
client possono creare e utilizzare istanze, se e visualizzabile 
dagli utenti in un browser, se e un controllo ActiveX, e se puo 
essere aggregato (agisce come parte di un composito). 

Le definizioni e le dichiarazioni per la CoClass (trattatta nel 
prosieguo del capitolo). 

Nome, versione e GUID della enumerazione, e informazioni 
per il collegamento alia Guida. 

Le definizioni e le dichiarazioni per il tipo enumerativo 
(trattatto nel prosieguo del capitolo). 
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Contenuto della pagina 

Nome, versione e GUID della enumerazione, il tipo che l'alias 
rappresenta e informazioni per il collegamento alia Guida. 

Le definizioni e le dichiarazioni per l'alias (trattatto nel 
prosieguo del capitolo). 

Nome, versione e GUID del record e informazioni per il 
collegamento alia Guida. 

Le definizioni e le dichiarazioni per il record (trattatto nel 
prosieguo del capitolo). 

Nome, versione e GUID della union e informazioni per il 
collegamento alia Guida. 

Le definizioni e le dichiarazioni per la union (trattatta nel 
prosieguo del capitolo). 

Nome, versione, GUID e DLL associata per il modulo e 
informazioni per il collegamento alia Guida. 

Le definizioni e le dichiarazioni per il modulo (trattatto nel 
prosieguo del capitolo). 

Nome, ID di smistamento o punto d'ingresso della DLL e 
informazioni per il collegamento alia Guida. 

Tipo restituito del metodo, e un elenco di tutti i parametri con 
relativi tipi ed eventuali modificatori. 

Flag che indicano come i client possono vedere e utilizzare il 
metodo, se questo e un metodo predefinito per I'interfaccia e 
se e ricollocabile. 

Le definizioni e le dichiarazioni per il metodo (trattatto nel 
prosieguo del capitolo). 

Nome, ID di smistamento, tipi di metodo di accesso alia 
proprieta (getter o setter) e informazioni per il collegamento 
alia Guida. 

Tipo restituito del metodo di accesso alia proprieta e un 
elenco di tutti i parametri con relativi tipi ed eventuali 
modificatori. 

Flag che indicano come i client possono vedere e utilizzare la 
proprieta, se questa e un'impostazione predefinita per 
1'interfaccia, se la proprieta e ricollocabile, collegabile, e cosi 
via. 

Le definizioni e le dichiarazioni per il metodo di accesso alle 
proprieta (trattatto nel prosieguo del capitolo). 

Nome, valore, tipo (per const di modulo) e informazioni per il 
collegamento alia Guida. 

Flag che indicano come i client possono vedere e utilizzare la 
costante, se questa rappresenta un valore predefinito, se la 
costante e collegabile, e cosi via. 

Le definizioni e le dichiarazioni per la costante (trattatta nel 
prosieguo del capitolo). 

Nome, tipo e informazioni per il collegamento alia Guida. 
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Tabella 39.3 Pagine del Type Library editor 





Pagina di 




Elemento 


informazione di 




Type Info 


tipo 


Contenuto della pagina 




Flags 


Flag che indicano come i client possono vedere e utilizzare il 




campo, se questo rappresenta un valore predefinito, se il 






campo e collegabile, e cosi via. 




Text 


Le definizioni e le dichiarazioni per il campo (trattatto nel 






prosieguo del capitolo). 



Per informazioni piu particolareggiate sulle varie opzioni che e possibile impostare 
nelle pagine delle informazioni di tipo, consultare la Guida in linea del Type Library 
editor. 

E possibile utilizzare tutte le pagine delle informazioni di tipo per vedere o 
modificare i valori in esse visualizzate.La maggior parte delle pagine organizza le 
informazioni in una serie di controlli, consentendo sia l'immissione di valori sia la 
loro selezione da un elenco, senza dover necessariamente conoscere la sintassi delle 
dichiarazioni corrispondenti. In questo modo e possibile prevenire molti piccoli 
errori come quelli di battitura durante la specif ica di valori da una serie limitata. 
Tuttavia, per alcuni potrebbe risultare piu rapido immettere direttamente le 
dichiarazioni. Per fare cio, utilizzare la pagina Text. 

Tutti gli elementi della libreria di tipi hanno una pagina di testo che visualizza la 
sintassi dell'elemento. Questa sintassi appare in un subset dell'IDL dell'Interface 
Definition Language di Microsoft. Qualsiasi modifica apportata in altre pagine 
dell'elemento viene riportata nella pagina di testo. Se si aggiunge del codice 
direttamente nella pagina Text, le modifiche vengono riportate nelle altre pagine del 
Type Library editor. 

II Type Library editor genera errori di sintassi se si aggiungono identif icatori che non 
sono supportati attualmente dall'editor; l'editor supporta attualmente solamente 
quegli identificatori che fanno riferimento al supporto per le libreria di tipi (non 
supportano RPC ne i costrutti utilizzati dal compilatore IDL di Microsoft per la 
generazione di codice sorgente C++ o per il supporto del marshaling). 

Elementi del Type Library editor 



A prima vista, l'interfaccia del Type Library editor pud sembrare molto complicata. 
Cio e dovuto al fatto che presenta informazioni su un elevato numero di elementi, 
ognuno dei quali ha caratteristiche proprie. Comunque, molte di queste 
caratteristiche sono comuni a tutti gli elementi. Ad esempio, ogni elemento (incluso 
la stessa libreria di tipi) ha le seguenti caratteristiche: 

• AUn Name, utilizzato per descrivere l'elemento e per fare riferimento aU'elemento 
nel codice. 

• Un GUID (identificatore globalmente univoco), un valore globalmente univoco a 
128-bit utilizzato da COM per identificare l'elemento. Questo dovrebbe essere 
sempre fornito per la stessa libreria di tipi, per le CoClass e per le interfacce. 
Altrimenti e facoltativo. 
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• Un Version number, per distingue tra piu versioni dell'elemento. Questo e sempre 
facoltativo, ma dovrebbe essere fornito per CoClass e interfacce, poiche senza di 
esso alcuni strumenti non sono in grado di utilizzarli. 

• Informazioni che collegano l'elemento a un argomento della Guida. Queste 
includono un valore Help String, Help Context o Help String Context. Help 
Context e utilizzato per un sistema di Guida tradizionale di Windows, in cui la 
libreria di tipi ha un file di Guida a se stante. Help String Context si utilizza 
quando la Guida e fornita invece da una DLL separata. Help Context o Help String 
Context fa riferimento a un file di Guida o a una DLL specificate nella pagina 
Attributes della libreria di tipi. L'informazione e sempre e facoltativa. 

Interfacce 

Un' interfaccia descrive i metodi (e qualsiasi proprieta espressa come funzione 'get' e 
' set') per un oggetto a cui si deve accedere tramite una tabella virtuale delle funzioni 
(Vtable). Se un'interfaccia e contrassegnata come duale, ereditera da IDispatch, e 
l'oggetto, tramite OLE automation, sara in grado di eseguire il binding anticipato, di 
accedere alia vtable e di eseguire il binding in esecuzione. Per impostazione 
predefinita, la libreria di tipi contrassegna come duali tutte le interfacce aggiunte 
dall'utente. 

Le interfacce possono essere membri assegnati: metodi e proprieta. Questi appaiono 
nel pannello Object list come figli del nodo dell'interfaccia. Le proprieta delle 
interfacce sono rappresentate dai metodi 'get' e 'set' utilizzati per leggere e scrivere i 
dati associati alia proprieta. Esse vengono rappresentate nella vista ad albero 
mediante delle icone particolari che ne indicano lo scopo. 

Se una proprieta e specificata come Write By Reference, vuol dire che viene passata 
come puntatore piuttosto che per valore. Alcune applicazioni, come Visual Basic, 
usano Write By Reference, se presente, per ottimizzare le prestazioni. Per passare la 
proprieta solamente per riferimento invece che per valore, utilizzare il tipo di 
proprieta By Reference Only. Per passare la proprieta per riferimento e per valore, 
scegliere Read I Write I Write By Ref . Per richiamare questo menu, selezionare sulla 
barra strumenti la freccia accanto all'icona della proprieta. 

Una volta aggiunte le proprieta o i metodi utilizzando il pulsante della barra 
strumenti o il menu contestuale del pannello Object list, se ne descrivono sintassi e 
attributi selezionando la proprieta o il metodo e utilizzando le pagine delle 
informazioni di tipo. 

La pagina Attributes consente di assegnare alia proprieta o al metodo un nome e l'ID 
di smistamento (in modo da poterla chiamare utilizzando IDispatch). Per le proprieta, 
si deve assegnare anche un tipo. La firma della funzione viene creata utilizzando la 
pagina Parameters, in cui e possibile aggiungere, rimuovere e riordinare parametri, 
impostarne il tipo ed eventuali modificatori, e specificare i tipi restituiti della 
funzione. 

Si noti che quando si assegnano proprieta e metodi a un'interfaccia, essi vengono 
assegnati implicitamente alia CoClass associata. Cio e dovuto al fatto che il Type 
Library editor non consente di aggiungere direttamente proprieta e metodi a una 
CoClass. 
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Dispinterface 

Le interfacce sono utilizzate piu frequentemente delle dispinterface per descrivere 
proprieta e metodi di un oggetto. Le dispinterface sono accessibili solamente tramite 
binding dinamico, mentre le interfacce possono disporre del bind statico tramite una 
vtable. 

E possibile aggiungere metodi e proprieta alle dispinterfaces secondo le stesse 
modalita usate per le interfacce. Comunque, quando si crea una proprieta per una 
dispinterface, non e possibile specificare il genere della funzione o i tipi dei 
parametri. 

CoClass 

Una CoClass descrive un oggetto COM univoco che implementa un o piu interfacce. 
Quando si definisce una CoClass, e necessari specificare qual e l'interfaccia 
implementata predefinita dell'oggetto e, facoltativamente, quale dispinterface e la 
sorgente predefinita per gli eventi. Notare che nel Type Library editor non si 
aggiungono proprieta o metodi a una CoClass. Proprieta e metodi vengono esposti ai 
client dalle interfacce, che a loro volta vengono associate alle CoClass usando la 
pagina Implements. 

Definizioni di tipo 

Enumerativi, alias, record e union dichiarano tutti tipi che potrebbero essere quindi 
utilizzati altrove nella libreria di tipi. 

Gli Enums sono costituiti da un elenco di costanti, ognuno delle quali deve essere 
numerica. L'input numerico normalmente e un intero in formato decimale o 
esadecimale. Per impostazione predefinita, il valore di base e zero. E possibile 
aggiungere costanti all'enumerativo selezionandolo nel pannello Object list e facendo 
clic sul pulsante Const sulla barra strumenti, oppure selezionando il comando New I 
Const nel menu contestuale del pannello Object list. 

Si raccomanda vivamente di prevedere una serie di stringhe di guida per gli 
enumerativi, in modo da renderne chiaro il significato. Qui di seguito viene riportato 
un esempio di immissione di un tipo enumerativo per il pulsante di un mouse e 
include una stringa di guida per ogni elemento enumerativo. 

typedef enum TxMouseButton 
{ 

[helpstringC'mbLeft") ] 
mbLeft = 0, 

[helpstringC'mbRight) ] 
robRight = 1. 

[helpstringf "mbMiddle) ] 
mbMiddle = 2 
} TxMouseButton; 

Un alias crea un alias (typedef) per un tipo. E possibile utilizzare l'alias per definire 
tipi che si vogliono utilizzare in altre informazioni di tipo quali record o union. 
Associare l'alias con la relativa definizione di tipo impostando l'attributo Type nella 
pagina Attributes. 
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Un record e una struttura in stile C. Un record e costituito da una lista di membri 
della struttura o campi. Una union definisce una union in stile C. Analogamente a un 
record, una union e costituita da una lista di membri della struttura o campi. 
Comunque, diversamente dai membri dei record, ogni membro di una union occupa 

10 stesso indirizzo fisico, e pertanto e possibile memorizzare un solo valore logico. 

Aggiungere i campi a un record o a una union selezionandolo nel pannello Object list 
e facendo clic sul pulsante del campo sulla barra strumenti, oppure facendo clic 
destro e scegliendo dal menu contestuale del pannello Object list l'opzione Field. 
Ogni campo ha un nome e un tipo che viene assegnato selezionando il campo e 
assegnandogli dei valori tramite la pagina Attributes. Record e union possono essere 
definite con un tag facoltativo, come con uno struct del C. 

I membri possono essere di un qualsiasi tipo incorporato; e anche possibile 
specificarne uno usando un alias prima di definire il record. 

C++Builder non supporta il marshaling delle parole chiave correlate a structs e union, 
come switch_type, first_is, last_is ecc. 

Moduli 

Un modulo definisce un gruppo di funzioni, di solito una serie di punti d'ingresso 
nelle DLL. Un modulo puo essere definito 

• Specificando sulla pagina degli attributi la DLL che esso rappresenta. 

• Aggiungendo metodi e costanti tramite la barra strumenti o il menu contestuale 
del pannello Object list. Per ogni metodo o costante, e necessario poi definirne gli 
attributi selezionandolo nel pannello Object list e impostandone i valori sulla 
pagina Attributes. 

Per i metodi di modulo, si deve assegnare un nome e un punto di ingresso per la DLL 
utilizzando la pagina degli attributi. Dichiarare i parametri e il tipo restituito della 
funzione usando la pagina dei parametri. 

Per costanti di modulo, utilizzare la pagina Attributes per specificare un nome, un 
tipo e un valore. 

11 Type Library editor non genera nessuna dichiarazione o implementazione relativa 
a un modulo. La DLL specificata deve essere creata come progetto separate 

Uso del Type Library editor 



Utilizzando l'editor delle librerie di tipi, e possibile creare nuove librerie di tipi o 
modificare quelle esistenti. Di solito, chi sviluppa applicazioni utilizza un wizard per 
creare gli oggetti esposti nella libreria di tipi, demandando a C++Builder la 
generazione automatica della libreria di tipi. Quindi, la libreria di tipi generata 
automaticamente viene aperta nel Type Library editor in modo da definire (o 
modificare) le interfacce, aggiungere definizioni di tipo, e cosi via. 

Comunque, anche se non si utilizza un wizard per definire gli oggetti, e possibile 
utilizzare il Type Library editor per definire una nuova libreria di tipi. In questo caso, 
si devono creare tutte le classi di implementazione, poiche il Type Library editor non 
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genera codice per le CoClass che non sono state associate mediante un wizard a una 
libreria di tipi. 

L'editor supporta un sottoinsieme di tipi validi in una libreria di tipi come descritto 
di seguito. 

Gli argomenti finali in questa sezione descrivono come: 

• Creare una nuova libreria di tipi 

• Aprire una libreria di tipi esistente 

• Aggiungere un'interfaccia alia libreria di tipi 

• Modificare un'interfaccia 

• Aggiungere proprieta e metodi alia libreria di tipi 

• Aggiungere un CoClass alia libreria di tipi 

• Aggiungere un'interfaccia a una CoClass 

• Aggiungere un enumerativo alia libreria di tipi 

• Aggiungere un alias alia libreria di tipi 

• Aggiungere un record o una union alia libreria di tipi 

• Aggiungere un modulo alia libreria di tipi 

• Salvare e registrare le informazioni della libreria di tipi 

Tipi consentiti 

II Type Library editor supporta in una libreria di tipi i seguenti tipi IDL. La colonna 
Compatibile con Automation specifica se il tipo puo essere utilizzato o meno da 
un'interfaccia i cui flag Automation o Dispinterface sono stati selezionati. Questi 
sono i tipi di cui COM e in grado di eseguire il marshaling automatico tramite la 
libreria di tipi. 



Tipo IDL 


Tipo variant 


Compatibile 
con 

Automation 


Descrizione 


short 


VT_I2 


Si 


Integer con segno a 2 byte 


long 


VT.I4 


Si 


Integer con segno a 4 byte 


single 


VT_R4 


Si 


Real a 4 byte 


double 


VT_R8 


Si 


Real a 8 byte 


CURRENCY 


VT_CY 


Si 


Valuta 


DATE 


VT.DATE 


Si 


data 


BSTR 


VT_BSTR 


Si 


Stringa binaria 


IDispatch 


VT_DISPATCH 


Si 


Puntatore all'interfaccia IDispatch 


SCODE 


VT_ERROR 


Si 


Codice di errore OLE 


VARIANT_BOOL 


VT_BOOL 


Si 


True = -1, False = 


VARIANT 


VT_VARIANT 


Si 


Puntatore a OLE Variant 


IUnknown 


VTJJNKNOWN 


Si 


Puntatore all'interfaccia IUnknown 


DECIMAL 


VT_DECIMAL 


Si 


virgola fissa a 16-byte 


byte 


VTJ1 


No* 


Integer con segno a 1 byte 


unsigned char 


VTUIl 


Si 


Integer senza segno a 1 byte 


unsigned short 


VTJJI2 


No* 


Integer senza segno a 2 byte 
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Tipo IDL 


Tipo variant 


Compatibile 

UUI 1 

Automation 


Descrizione 


unsigned long 


VTUI4 


No* 


Integer senza segno a 4 byte 


int64 


VT_I8 


No 


Real con segno a 8 byte 


uint64 


VTUI8 


No 


Real senza segno a 8 byte 


int 


VTJNT 


No* 


Integer dipendente dal sistema 
(Win32=Integer) 


unsigned int 


VT_UINT 


No* 


Integer senza segno dipendente dal 


void 


VT VOTD 


Si 


VOTD in stilp C 


HRESULT 


VT_HRESULT 


No 


Codice di errore a 32 bit 


SAFEARRAY 


VT_SAFEARRAY 


Si 


OLE Safe Array 


LPSTR 


VT_LPSTR 


No 


Stringa terminata con null 


LPWSTR 


VT_LPWSTR 


No 


Wide string terminata con null 



* Potrebbero essere compatibili con Automation con alcune applicazioni. 

II tipo unsigned char (VT_UI1) e compatibile con Automation, ma non ne e 
consentito l'uso in un Variant o Ole Variant poiche molti server Automation non 
gestiscono correttamente questo valore. 

Per i tipi consentiti nello sviluppo di applicazioni CORBA, consultare "Definizione 
delle interfacce deU'oggetto" a pagina 31-5. 

A parte questi tipi IDL, in una definizione della libreria di tipi si pud usare qualsiasi 
interfaccia e tipo definiti nella libreria o nelle librerie collegate. 

II Type Library editor memorizza nel file generato di libreria di tipi (.TLB) le 
informazioni di tipo in formato binario. 

Safe Array 

COM richiede che gli array siano passati tramite un tipo di dati speciale noto come 
SafeArray. I SafeArray possono essere creati e distrutti chiamando speciali funzioni 
COM , e tutti gli elementi di un SafeArray devono essere tipi consentiti e compatibili 
con Automation. 

Nel Type Library editor, un SafeArray deve specificare il tipo dei suoi elementi. Per 
esempio, la linea seguente prelevata dalla pagina Text dichiara un metodo con un 
parametro che e un SafeArray, il cui tipo dell'elemento e long: 

HRESULT _stdcall HighlightLines (SAFEARRAY (long) Lines); 

Sebbene sia necessario specificare il tipo dell'elemento quando si dichiara un tipo 
SafeArray nel Type Library editor, la dichiarazione nella unit _TLB generata non 
indica il tipo dell'elemento. 

Creazione di una nuova libreria di tipi 

Potrebbe essere necessario creare una libreria di tipi indipendente di un particolare 
oggetto COM. Per esempio, si potrebbe voler definire una libreria di tipi che 
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contenga definizioni di tipo che si utilizzano in molte altre librerie di tipi. In questo 
casi si pud creare una libreria di tipi di definizioni di base e aggiungerla alia pagina 
Uses di altre librerie di tipi. 

E anche possibile creare anche una libreria di tipi per un oggetto non ancora 
implementato. Una volta che la libreria di tipi contiene la definizione dell'interfaccia, 
e possibile utilizzare il COM Object wizard per generare una CoClass e 
l'implementazione. 

Per creare una nuova libreria di tipi: 

1 Scegliere File I New I Other per aprire la finestra di dialogo New Items. 

2 Scegliere la pagina ActiveX. 

3 Selezionare l'icona Type Library. 

4 Scegliere OK. 

II Type Library editor appare con la richiesta di immettere un nome per la libreria 
di tipi. 

5 Immettere il nome desiderata. Continuare ad aggiungere alia libreria di tipi gli 
elementi desiderati. 

Apertura di una libreria di tipi esistente 

Quando si usano i wizard per creare un controllo ActiveX, un oggetto Automation, 
ActiveForm, oggetti COM, oggetti transazionali, moduli dati remoti o moduli dati 
transazionali module, viene creata automaticamente una libreria di tipi con una unit 
di implementazione. Inoltre, si potrebbero avere librerie di tipi associate ad altri 
prodotti (server) disponibili nel sistema. 

Per aprire una libreria di tipi che non fa parte del progetto corrente: 

1 Scegliere il comando File I Open dal menu principale dell'IDE. 

2 Nella finestra di dialogo Open, impostare la casella File Type a "type library. 

3 Selezionare la libreria di tipi desiderata e scegliere Open. 
Per aprire una libreria di tipi associata al progetto corrente: 
1 Scegliere il comando View I Type Library. 

A questo punto, e possibile aggiungere interfacce, CoClass e altri elementi della 
libreria di tipi, come enumerazioni, proprieta e metodi. 

Quando si scrivono applicazioni client, non e necessario aprire la libreria di tipi. 
y Occorre solamente la unit Project_TLB che il Type Library editor crea a partire da una 
libreria di tipi, e non la libreria di tipi. E possibile aggiungere direttamente questo file 
a un progetto client, oppure, se la libreria di tipi e registrata nel sistema, si puo 
utilizzare la finestra di dialogo Import Type Library (comando Project I Import Type 
Library). 

Aggiunta di un'interfaccia alia libreria di tipi 

Per aggiungere un'interfaccia: 
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1 Nella barra strumenti fare clic sull'icona dell'interfaccia. 

Al pannello dell'elenco degli oggetti viene aggiunta un'interfaccia e compare la 
richiesta di inserire un nome. 

2 Scrivere un nome per l'interfaccia. 

La nuova interfaccia contiene gli attributi predefiniti che, se necessario, possono 
essere modificati. 

E possibile aggiungere proprieta (rappresentate dalle funzioni getter/ setter) e 
metodi adatti alia funzione dell'interfaccia. 

Modifica di un'interfaccia con il Type Library editor 

Esistono vari modi per modificare, una volta creata, un'interfaccia o una 
dispinterface. 

• E possibile modificare gli attributi dell'interfaccia utilizzando la pagina Type 
information che contiene le informazioni che si desiderano modificare. Selezionare 
l'interfaccia nel pannello Object list ed utilizzate i controlli sulla pagina opportuna 
delle informazioni di tipo. Per esempio, si potrebbe voler modificare l'interfaccia 
del genitore utilizzando la pagina Attributes, oppure utilizzare la pagina Flags per 
indicare se l'interfaccia e duale o meno. 

• E possibile modificare direttamente la dichiarazione dell'interfaccia selezionando 
l'interfaccia nel pannello Object list e modificando quindi le dichiarazioni sulla 
pagina Text. 

• E possibile aggiungere proprieta e metodi all'interfaccia (vedere piu avanti). 

• E possibile modificare le proprieta e metodi gia presenti nell'interfaccia 
modificandone le informazioni di tipo. 

• E possibile associarla a una CoClass selezionando la CoClass nel pannello Object 
list, facendo clic destro sulla pagina Implements e scegliendo Insert Interface. 

Se l'interfaccia e associata a una CoClass generata da un wizard, e possibile fare in 
modo che il Type Library editor applichi le modifiche al file di implementazione 
facendo clic sul pulsante Refresh sulla barra strumenti. 

Aggiunta di proprieta e metodi ad una interface o dispinterface 

Per aggiungere proprieta o metodi a una interface o dispinterface: 

1 Selezionare l'interfaccia, e scegliere l'icona delle proprieta o dei metodi dalla barra 
strumenti. Se si sta aggiungendo una proprieta, si pud fare clic direttamente 
sull'icona della proprieta per creare una proprieta di lettura/scrittura (con un 
getter e un setter), oppure fare clic sulla freccia verso il basso per visualizzare un 
menu di tipi della proprieta. 

Viene richiesta l'aggiunta di un nome; cio fatto, i membri del metodo per accesso 
alia proprieta o il membro del metodo vengono aggiunti al pannello Object list. 

2 Scrivere un nome per il membro. 
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II nuovo membro contiene impostazioni predefinite, visibili sulle pagine Attributes, 
Parameters e Flags, che e possibile modificare per adattarle al membro. Per esempio, 
potrebbe essere necessario assegnare un tipo a una proprieta usando la pagina 
Attributes. Se si sta aggiungendo un metodo, potrebbe essere necessario specificarne 
i suoi parametri sulla pagina Parameters. 

Come metodo alternative e possibile aggiungere proprieta e metodi scrivendo 
direttamente nella pagina Text e usando la sintassi IDL. Per esempio, nella pagina 
Text di un'interfaccia e possibile scrivere la seguente dichiarazione di proprieta: 

[ 

uuid(5FD36EEF-70E5-llDl-AA62-00C04FB16F42) , 

version(l.O) , 

dual, 

oleautomation 

] 

interface Interfacel: IDispatch 

{ // Add everything between the curly braces 

[propget, id ( 0x00000002 ) ] 

HRESULT _stdcall AutoSelect ( [out, retval] long Value ); 

[propget, id(0x00000003) ] 

HRESULT _stdcall AutoSizef [out, retval] VARIANT_BOOL Value ) ; 
[propput, id(0x00000003) ] 

HRESULT _stdcall AutoSizef [in] VARIANT_B00L Value ) ; 

}; 

Dopo aver aggiunto i membri ad una pagina del membro interfaccia, i membri 
appaiono come elementi distinti nel pannello dell'elenco degli oggetti, ciascuno con 
le proprie pagine di attributi, flag e parametri. E possibile modificare ogni nuova 
proprieta o metodo selezionandolo nel pannello Object list e utilizzando queste 
pagine, oppure apportando le modifiche direttamente nella pagina Text. 

Se l'interfaccia e associata a una CoClass generata da un wizard, facendo clic sul 
pulsante Refresh sulla barra strumenti e possibile fare in modo che il Type Library 
editor applichi le modifiche al file di implementazione. II Type Library editor 
aggiungera nuovi metodi alia classe di implementazione per aggiornarla in base ai 
nuovi membri. In seguito, sara possibile individuare i nuovi metodi nel codice 
sorgente della unit di implementazione e scriverne il corpo in modo da completare 
l'implementazione. 

Aggiunta di CoClass alia libreria di tipi 

II modo piu semplice per aggiungere una CoClass al progetto consiste nello scegliere 
dal menu principale nell'IDE il comando File I New I Other e utilizzare il wizard 
opportuno sulla pagina ActiveX o Multitier della finestra di dialogo New Items. II 
vantaggio di questo metodo sta nel fatto che, oltre ad aggiungere la CoClass e la 
relativa interfaccia alia libreria di tipi, il wizard aggiunge una unit di 
implementazione, aggiorna il file di progetto includendo la nuova unit di 
implementazione, e aggiunge la nuova CoClass alia mappa degli oggetti nel file di 
progetto. 

Se non si utilizza un wizard, comunque, e possibile creare una CoClass facendo clic 
sull'icona CoClass della barra strumenti e quindi specif icandone gli attributi. Si vorra 
assegnare un nome alia nuova CoClass (pagina Attributes), e utilizzare la pagina 
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Flags per inserire informazioni sulla CoClass, ad esempio, se e un oggetto 
applicazione, se rappresenta un controllo ActiveX, e cosi via. 

Se si aggiunge una CoClass a una libreria di tipi utilizzando la barra strumenti invece 
di un wizard, si dovra generare manualmente l'implementazione della CoClass e 
aggiornarla ogni volta che si modifica un elemento in una delle interfacce della 
CoClass. Quando si aggiunge manualmente l'implementazione di una CoClass, 
accertarsi di aggiungere la nuova CoClass alia mappa degli oggetti nel file di 
progetto. 

Non e possibile aggiungere membri a un CoClass in modo diretto. I membri vengono 
aggiunti in modo implicito quando si aggiunge un'interfaccia alia CoClass. 

Aggiunta di un'interfaccia a una CoClass 

Le CoClass sono definite dalle interfacce che esse rendono disponibili ai client. 
Benche sia possibile aggiungere alia classe di implementazione di una CoClass tutte 
le proprieta e metodi desiderati, i client possono vedere solo quelle proprieta e quei 
metodi che vengono esposti dalle interfacce associate con la CoClass. 

Per associare un'interfaccia con una CoClass, fare clic destro nella pagina 
Implements della classe e scegliere Insert Interface in modo da visualizzare un elenco 
di interfacce tra cui effettuare la scelta. L'elenco include le interfacce definite nella 
libreria di tipi corrente e quelle definite in una qualsiasi libreria di tipi referenziata 
nella libreria di tipi corrente. Scegliere l'interfaccia che dovra essere implementata 
dalla classe. L'interfaccia viene aggiunta alia pagina con il relativo GUID e gli altri 
attributi. 

Se la CoClass e stata generato usando un wizard, il Type Library editor aggiorna 
automaticamente la classe di implementazione includendo lo scheletro di base dei 
metodi per quei metodi (inclusi i metodi per l'accesso alle proprieta) di tutte le 
interfacce aggiunte in questo modo. 

Aggiunta di una Enumeration alia libreria di tipi 

Per aggiungere enumerativi ad una libreria di tipi: 

1 Sulla barra strumenti fare clic sull'icona enum. 

Un tipo enum viene aggiunto al pannello Object list e compare la richiesta di 
inserire un nome. 

2 Scrivere un nome per l'enumerativo. 

II nuovo enum e vuoto e contiene gli attributi predefiniti nella pagina Attributes 
dove e possibile modificarli. 

Aggiungere i valori alia enumerazione facendo clic sul pulsante New Const. Quindi 
selezionare ciascun valore enumerato e assegnargli il nome (e possibilmente un 
valore) usando la pagina degli attributi. 

Una volta aggiunto un enumerativo, il nuovo tipo e disponibile per l'utilizzo da parte 
della libreria di tipi o di qualsiasi altra libreria di tipi che contenga un riferimento ad 
esso nella pagina Uses. Ad esempio, e possibile utilizzare l'enumerativo come tipo di 
una proprieta o di un parametro. 
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Aggiunta di un alias alia libreria di tipi 

Per aggiungere un alias a una libreria di tipi: 

1 Sulla barra strumenti, fare clic su sull'icona dell'alias. 

Un tipo alias verra aggiunto al pannello Object list e apparira la richiesta di 
aggiungere un nome. 

2 Scrivere un nome per l'alias. 

Per impostazione predefinita, il nuovo alias e di tipo long.Utilizzare la pagina 
Attributes per modificarlo nel tipo che si vuole sia rappresentato dall'alias. 

Una volta aggiunto un alias, il nuovo tipo e disponibile per l'utilizzo da parte della 
libreria di tipi o di qualsiasi altra libreria di tipi che contenga un riferimento ad esso 
nella pagina Uses. Ad esempio, e possibile utilizzare l'alias come tipo di una 
proprieta o di un parametro. 

Aggiunta di un record o di una union alia libreria di tipi 

Per aggiungere un record o una union a una libreria di tipi: 

1 Sulla barra strumenti, fare clic sull'icona del record o su quella della union. 

L'elemento di tipo selezionato verra aggiunto al pannello Object list e apparira la 
richiesta di aggiungere un nome. 

2 Scrivere un nome per il record o per la unione. 

A questo punto, il nuovo record o la union non contengono campi. 

3 Dopo aver selezionato il record o la union nel pannello Object list, fare clic 
sull'icona Field nella barra strumenti. Specificare nome e tipo di campo 
utilizzando la pagina Attributes. 

4 Ripetere il passo 3 per tutti i campi necessari. 

Una volta definito un record o una union, il nuovo tipo e disponibile per l'utilizzo da 
parte della libreria di tipi o di qualsiasi altra libreria di tipi che contenga un 
riferimento ad esso nella pagina Uses. Ad esempio, e possibile utilizzare il record o la 
union come tipo di una proprieta o di un parametro. 

Aggiunta di un modulo alia libreria di tipi 

Per aggiungere un modulo a una libreria di tipi: 

1 Sulla barra strumenti, fare clic su sull'icona del modulo. 

II modulo scelto verra aggiunto al pannello di Object list e e apparira la richiesta di 
aggiungere un nome. 

2 Scrivere un nome per il modulo. 

3 Sulla pagina Attributes, specificare il nome della DLL di cui il modulo ne 
rappresenta il punto d'ingresso. 
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4 Aggiungere tutti i metodo dalla DLL specificata al punto 3, facendo clic sull'icona 
Method nella barra strumenti, e utilizzando successivamente le pagine degli 
attributi per descrivere il metodo. 

5 Aggiungere tutte le costanti che si vuole vengano definite dal modulo facendo clic 
su sull'icona Const sulla barra strumenti. Per ogni costante, specificare nome, tipo 
e valore. 

Salvataggio e registrazione delle informazioni della libreria di tipi 

Dopo aver modificato la libreria di tipi, sara necessario salvare e registrare le 
informazioni relative. 

II salvataggio di una libreria di tipi aggiorna automaticamente: 

• II file binario della libreria di tipi (estensione .tlb). 

• La unit Project_TLB che ne rappresenta i contenuti 

• II codice dell'implementazione di tutte le CoClass generate da un wizard. 

La libreria di tipi viene registrata come file binario separato (.TLB), ma viene anche 
eseguito il link nel server (.EXE, DLL o .OCX). 

II Type Library editor fornisce le opzioni per memorizzare le informazioni della 
libreria di tipi. II modo prescelto per questa operazione dipende dallo stadio a cui si e 
giunti nell'implementazione della libreria di tipi: 

• Save, per salvare entrambe le unit .TLB e la unit Project JTLB sul disco. 

• Refresh, per aggiornare le unit della libreria di tipi solo in memoria. 

• Register, per aggiungere un elemento della libreria di tipi nel registro di sistema di 
Windows. L'operazione viene eseguita automaticamente se il server con cui e 
associato il file .TLB e esso stesso registrato. 

• Export, per salvare un file IDL contenente le definizione dei tipi e delle interfacce 
secondo la sintassi IDL. 

Tutti i metodi precedenti eseguono un controllo della sintassi. Quando si aggiorna, 
registra o salva la libreria di tipi, C++Builder aggiorna automaticamente la unit di 
implementazione di ogni CoClasses che e stata creata usando un wizard. 

Salvataggio di una libreria di tipi 

II salvataggio di una libreria di tipi 

• Esegue un controllo sintattico e di validita. 

• Salva le informazioni in un file .TLB. 

• Salva le informazioni nella unit ProjectJTLB. 

• Notifica al gestore del modulo IDE di aggiornare l'implementazione nel caso la 
libreria di tipi sia associata a una CoClass che e stata generata da un wizard. 

Per salvare la libreria di tipi, scegliere File I Save dal menu principale di C++Builder. 

Aggiornamento della libreria di tipi 

L'aggiornamento della libreria di tipi 



Funzionamento delle librerie di tipi 39-19 



Distribuzione delle librerie di tipi 

• Esegue il controllo della sintassi. 

• Rigenera le unit della libreria di tipi di C++Builder solo in memoria. Non salva 
alcun file su disco. 

• Notifica al gestore del modulo IDE di aggiornare l'implementazione nel caso la 
libreria di tipi sia associata a una CoClass che e stata generata da un wizard. 

Per aggiornare la libreria di tipi scegliere l'icona Refresh nella barra strumenti del 
Type Library editor. 

Se sono stati ridenominati degli elementi nella libreria di tipi, l'aggiornamento 
dell'implementazione pud creare elementi duplicati. In questo caso, occorre spostare 
il codice nel punto corretto e cancellare i doppioni. Analogamente, se si cancellano 
elementi nella libreria di tipi, l'aggiomamento dell'implementazione non li rimuove 
dalle CoClasses (partendo dal presupposto che si stia rimuovendo solo la loro 
visibility ai client). Se non sono piu necessari, si dovra cancellare manualmente questi 
elementi nella unit di implementazione. 

Registrazione della libreria di tipi 

Di solito, non e necessario registrare esplicitamente una libreria di tipi in quanto essa 
si registra automaticamente al momento della registrazione dell'applicazione COM 
server (consultare "Registrazione di un oggetto COM" a pagina 41-17). Comunque, 
quando si crea una libreria di tipi utilizzando il Type Library wizard, essa non e 
associata con un oggetto server. In questo caso, e possibile registrare la libreria di tipi 
utilizzando direttamente la barra strumenti. 

La registrazione della libreria di tipi: 

• Esegue un controllo della sintassi 

• Aggiunge un elemento per la libreria di tipi nel registro di Windows 

Per registrare la libreria di tipi, scegliere l'icona Register nella barra strumenti del 
Type Library editor. 

Esportazione di un file IDL 

L'esportazione di una libreria di tipi: 

• Esegue il controllo della sintassi. 

• Crea un file IDL contenente le dichiarazioni delle informazioni di tipo. Questo file 
descrive le informazioni di tipo secondo la sintassi IDL di Microsoft. 

Per esportare la libreria di tipi, scegliere l'icona Export nella barra strumenti del Type 
Library editor. 

Distribuzione delle librerie di tipi 



Per impostazione predefinita, se una libreria di tipi e stata creata come parte di un 
progetto di un server ActiveX o Automation, essa viene collegata automaticamente al 
file .DLL, .OCX o EXE sotto forma di risorsa. 
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E possibile, tuttavia, distribuire l'applicazione con la libreria di tipi sotto forma di file 
.TLB distinto, in quanta C++Builder, se lo si preferisce, e in grado di eseguire la 
manutenzione della libreria di tipi. 

Storicamente, le librerie di tipi per le applicazioni Automation erano memorizzate 
come fili distinti con estensione .TLB. Ora, la tipiche applicazioni di Automation 
compilano le librerie di tipi direttamente nei file .OCX o .EXE. II sistema operativo 
presume che la libreria di tipi sia la prima risorsa nel file eseguibile (.OCX o .EXE). 

Quando si rendono disponibili agli sviluppatori di applicazione altre librerie di tipi 
che non siano quella del progetto principale, esse possono essere in una qualsiasi 
delle seguenti forme: 

• Una Risorsa. Questa risorsa avra il tipo TYPELIB e un intero ID. Se si sceglie di 
costruire librerie di tipi con un compilatore di risorse, occorre dichiararlo nel file 
risorsa (.RC) nel modo seguente: 

1 typelib mylibl.tlb 

2 typelib mylib2.tlb 

In una libreria ActiveX ci possono essere piu risorse di libreria di tipi. Gli 
sviluppatori di applicazioni usano il compilatore di risorse per aggiungere il file 
.TLB alia propria libreria ActiveX. 

• File binari indipendenti. II file .TLB generato dal Type Library editor e un file 
binario. 
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Capitolo 




Creazione di client COM 



I client COM sono applicazioni che fanno uso di un oggetto COM implementato da 
un'altra applicazione o da una libreria. I tipi piu comuni sono applicazioni che 
controllano un Automation server (Automation controller) e applicazioni che 
ospitano un controllo ActiveX (ActiveX container). 

A prima vista questi due tipi di client COM sono molto diversi: L' Automation 
controller tipico lancia un server EXE esterno e impartisce dei comandi per far si che 
quel server esegua dei compiti per suo conto. L' Automation server di solito e non 
visuale e out-of -process. II tipico client ActiveX, d'altro canto, ospita un controllo 
visuale, utilizzandolo in modo molto simile a come si utilizza un qualsiasi controllo 
sulla Component palette. I server ActiveX sono sempre server in-process. 

Comunque, le operazioni per la scrittura questi due tipi di client COM sono 
notevolmente simili: L'applicazione client ottiene un'interfaccia per l'oggetto server e 
ne usa proprieta e metodi. C++Builder semplifica tutto cio consentendo di avvolgere 
la CoClass del server in un componente sul client, che sara possibile installare anche 
sulla Component palette. Esempi di tali wrapper di componenti appaiono su due 
pagine della Component palette: esempi di wrapper ActiveX appaiono sulla pagina 
ActiveX e esempi di oggetti Automation appaiono sulla pagina Servers. 

Quando si scrive un client COM, e necessario comprendere 1' interfaccia che il server 
espone ai client, esattamente come si devono comprendere proprieta e metodi di un 
componente della Component palette per poterlo utilizzarlo nelle applicazioni. 
Questa interfaccia (o insieme di interfacce) e determinata dall'applicazione server, e 
di solito resa pubblica in una libreria di tipi. Per informazioni specifiche sulle 
interfacce rese pubbliche di una particolare applicazione server, si dovrebbe 
consultare la documentazione di quella applicazione. 

Anche se si sceglie di non avvolgere un oggetto server in un wrapper di componenti 
e di non installarlo sulla Component palette, occorre rendere disponibile 
all'applicazione la sua definizione di interfaccia. Per fare cio e possibile importare le 
informazioni di tipo del server. 
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E anche possibile richiedere direttamente le informazioni di tipo utilizzano le API di 
COM, ma C++Builder non fornisce un particolare supporto adatto alio scopo. 

Alcune vecchie tecnologie COM, come OLE (Object Linking and Embedding) non 
forniscono informazioni di tipo in una libreria di tipi. Si appoggiano, invece, ad un 
set standard di interfacce predefinite. L'argomento e trattato nella sezione 
"Creazione di client per server che non hanno una libreria di tipi" a pagina 40-17. 



Importazione di informazioni della libreria di tipi 



Per rendere disponibili all'applicazione client le informazioni sul server COM 
occorre importare le informazioni sul server memorizzate nella libreria di tipi del 
server. L'applicazione potra utilizzare quindi le classi generate risultanti per 
controllare l'oggetto server. 

Esistono due modi per importare le informazioni della libreria di tipi: 

• E possibile utilizzare la finestra di dialogo Import Type Library per importare 
tutte le informazioni disponibili sui tipi, sugli oggetti e sulle interfacce del server. 
Questo e il metodo piu generale, in quanta consente di importare informazioni da 
qualsiasi libreria di tipi e puo generare, all'occorrenza, wrapper di componenti per 
tutte le CoClasses creabili, incluse nella libreria di tipi e non contrassegnate come 
Hidden, Restricted o PreDeclID. 

• Se si sta eseguendo l'importazione dalla libreria di tipi di un controllo ActiveX, e 
possibile utilizzare la finestra di dialogo Import ActiveX. L'operazione importa le 
stesse informazioni di tipo, ma crea wrapper di componenti solamente per le 
CoClass che rappresentano controlli ActiveX. 

• E possibile utilizzare il programma di utilita della riga comandi tlibimp.exe che 
dispone di ulteriori opzioni di configurazione non disponibili dall'intemo 
dell'IDE. 

• Una libreria di tipi generata utilizzando un wizard viene importata 
automaticamente utilizzando lo stesso meccanismo utilizzato dalla voce di menu 
Import type library. 

Indipendentemente dal metodo scelto per importare informazioni della libreria di 
tipi, la finestra di dialogo risultante crea una unit di nome TypeLibNameJTLB, dove 
TypeLibName e il nome della libreria di tipi. Questo file contiene le dichiarazioni per 
le classi, i tipi e le interfacce definite nella libreria di tipi. Includendolo nel progetto, 
quelle definizioni saranno disponibili all'applicazione, rendendo cosi possibile creare 
oggetti e chiamarne le interfacce. Questo file puo essere ricreato dall'IDE di tanto in 
tanto; pertanto, non e consigliabile apportare manualmente modifiche al file. 

Oltre ad aggiungere le definizioni di tipo alia unit TypeLibName_TLB, la finestra di 
dialogo puo creare anche wrapper della classe VCL per tutte le CoClass definite nella 
libreria di tipi, che mettera in una unit separata di nome TypeLibName_OCX. Quando 
si utilizza la finestra di dialogo Import Type Library, la creazione di questi wrapper e 
facoltativa. Quando si utilizza la finestra di dialogo Import ActiveX, questi wrapper 
vengono sempre generati per tutte le CoClass che rappresentano controlli. 
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Se si stanno generando wrapper di componenti, la finestra di dialogo di 
importazione genera la unit TypeLibNameJDCX, ma non la aggiunge al progetto. 
(Aggiunge solamente la unit TypeLibNameJTLB). E possibile aggiungere 
esplicitamente al progetto la unit TypeLibNameJDCX scegliendo l'opzione Project I 
Add to Project. 

I wrapper di classe generati rappresentano le CoClass all'applicazione, ed espongono 
le proprieta e i metodi delle sue interfacce. Se una CoClass supporta le interfacce per 
la generazione di eventi (IConnectionPointContainer e IConnectionPoint), il wrapper 
della classe VCL crea un convogliatore di eventi in modo che l'assegnazione dei 
gestori di evento risulti semplice come per qualsiasi altro componente. Se nella 
finestra di dialogo si sceglie di installare le classi VCL generate nella Component 
palette, e possibile utilizzare l'Object Inspector per assegnare valori di proprieta e 
gestori di evento. 

La finestra di dialogo Import Type Library non crea wrapper di classe per oggetti 
evento di COM+. Per scrivere un client che risponda agli eventi generati da un 
oggetto evento di COM+, si deve creare da programma il convogliatore dell'evento. 
Questo procedimento e descritto in "Gestione di eventi COM+" a pagina 40-16. 

Per maggiori informazioni sul codice generato durante l'importazione di una libreria 
di tipi, consultare "Codice generato durante l'importazione delle informazioni di una 
libreria di tipi" a pagina 40-5. 



Uso della finestra di dialogo Import Type Library 



Per importare una libreria di tip: 

1 Scegliere il comando Project I Import Type Library. 

2 Selezionare dall'elenco la libreria di tipi. 

La finestra di dialogo elenca tutte le librerie di tipi registrate nel sistema. Se la 
libreria non si trova nell'elenco, scegliere il pulsante Add, cercare e selezionare il 
file di libreria di tipi, scegliere OK. In questo modo si registra la libreria di tipi, 
rendendola pertanto disponibile. Quindi ripetere il punto 2. Si noti che la libreria 
di tipi potrebbe essere un file di libreria indipendente (.tlb, .olb), oppure un server 
che mette a disposizione una libreria di tipi (.dll, .ocx, .exe). 

3 Se si vuole generare un componente VCL che avvolga una CoClass nella libreria di 
tipi, selezionare l'opzione Generate Component Wrapper. Se non si vuole 
generare il componente, si puo sempre utilizzare la CoClass utilizzando le 
definizioni nella unit TypeLibNameJTLB. Tuttavia, sara necessario scrivere 
personalmente le chiamate per creare l'oggetto server e, se occorre, impostare un 
convogliatore di eventi. 

La finestra di dialogo Import Type importa solo le CoClass il cui flag CanCreate e 
impostato e i cui flag Hidden, Restricted o PreDeclID non sono impostati. Questi 
flag possono essere ridefiniti utilizzando il programma di utilita della riga 
comandi tlibimp.exe. 

4 Se non si vuole installare nella Component palette il wrapper di componenti 
generato, scegliere Create Unit. L'operazione genera la unit TypeLibNameJTLB e, se 
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al punto 3 e stata selezionata l'opzione Generate Component Wrapper, la unit 
TypeLibNameJDCX. Questo conclude anche le operazioni nella finestra di dialogo 
Import Type Library. 

5 Se si vuole installare nella Component palette il wrapper di componenti generato, 
selezionare la pagina della Component palette su cui dovra risiedere questo 
componente e scegliere l'opzione Install. L'operazione genera le unit 
TypeLibNameJTLB e TypeLibNameJDCX, analogamente al pulsante Create Unit, 
quindi visualizza la finestra di dialogo Install component che consente di 
specificare il package in cui collocare i componenti (sia esso un package esistente o 
uno nuovo). II pulsante risulta disattivato (grigio) nel caso non sia possibile creare 
un componente per la libreria di tipi. 

Appena si esce dalla finestra di dialogo Import Type Library, le nuove unit 
TypeLibNameJTLB e TypeLibNameJDCX appariranno nella directory specificata dal 
controllo Unit dir name. La unit TypeLibName_TLB contiene le dichiarazioni per gli 
elementi definiti nella liberia di tipi. La unit TypeLibNameJDCX contiene il wrapper 
di componenti generato, nel caso sia stata selezionata l'opzione Generate Component 
Wrapper. 

Inoltre, se e stato installato il wrapper di componenti generato, a questo punto nella 
Component Palette risiede un oggetto server descritto dalla libreria di tipi. E 
possibile utilizzare l'Object Inspector per impostare le proprieta o per scrivere un 
gestore di evento per il server. Se si aggiunge il componente a una scheda o ad un 
modulo dati, in fase di progettazione e possibile farvi clic destro per visualizzarne la 
pagina di proprieta (nel caso la supporti). 

La pagina Servers della Component palette contiene diversi esempi di Automation 
server importati nel modo appena descritto. 



Uso della finestra di dialogo Import ActiveX 



Per importare un controllo ActiveX: 

1 Scegliere l'opzione Component I Import ActiveX Control. 

2 Selezionare dall'elenco la libreria di tipi. 

La finestra di dialogo elenca tutte le librerie di tipi registrate nel sistema che 
definiscono controlli ActiveX. (Questo e un sottoinsieme delle librerie elencate 
nella finestra di dialogo Import Type Library). Se la libreria non si trova 
nell'elenco, scegliere il pulsante Add, cercare e selezionare il file di libreria di tipi, 
scegliere OK. In questo modo si registra la libreria di tipi, rendendola pertanto 
disponibile. Quindi ripetere il punto 2. Si noti che la libreria di tipi potrebbe essere 
un file di libreria indipendente (.tlb, .olb), oppure un server ActiveX (.dll, .ocx). 

3 Se non si vuole installare nella Component palette il controllo ActiveX, scegliere 
Create Unit. L'operazione genera la unit TypeLibNameJTLB e la unit 
TypeLibNameJDCX. Questo conclude anche le operazioni nella finestra di dialogo 
Import ActiveX. 

4 Se si vuole installare nella Component palette il controllo ActiveX, selezionare la 
pagina della Component palette su cui dovra risiedere questo componente e 
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scegliere l'opzione Install. L'operazione genera le unit TypeLibNameJTLB e 
TypeLibNameJDCX, analogamente al pulsante Create Unit, quindi visualizza la 
finestra di dialogo Install component che consente di specificare il package in cui 
collocare i componenti (sia esso un package esistente o uno nuovo). 

Appena si esce dalla finestra di dialogo Import ActiveX, le nuove unit 
TypeLibName JJLB e TypeLibNameJDCX appariranno nella directory specificata dal 
controllo Unit dir name. La unit TypeLibNameJTLB contiene le dichiarazioni per gli 
elementi definiti nella liberia di tipi. La unit TypeLibNameJDCX contiene il wrapper 
di componenti generato per il controllo ActiveX. 

A differenza della finestra di dialogo Import Type Library in cui l'opzione e 
facoltativa, la finestra di dialogo Import ActiveX genera sempre un wrapper di 
componenti. II motivo dipende dal fatto che, essendo un controllo visuale, un 
controllo ActiveX necessita del supporto aggiuntivo del wrapper di componenti per 
poter essere collocato sulle schede VCL. 

Inoltre, se il componente wrapper generato e stato installato, a questo punto nella 
Component Palette risiede un controllo ActiveX. E possibile utilizzare l'Object 
Inspector per impostare le proprieta o per scrivere i gestori di evento del controllo. Se 
si aggiunge il controllo a una scheda o a un modulo dati, in fase di progettazione e 
possibile farvi clic destro per visualizzare la pagina di proprieta (nel caso la 
supporti). 

La pagina ActiveX della Component palette contiene diversi esempi di controlli 
ActiveX importati nel modo appena descritto. 



Codice generato durante I'importazione delle informazioni di una 
libreria di tipi 



Dopo aver importato una libreria di tipi, e possibile visualizzare la unit 
TypeLibNameJTLB generata. II file sorgente di questa unit definisce le costanti che 
assegnano nomi simbolici ai GUID della libreria di tipi e alle sue interfacce e CoClass. 
I nomi delle costanti sono generati come segue: 

• II GUID per la libreria di tipi assume il formato LIBlDJTypeLibName, in cui 
TypeLibName e il nome della libreria di tipi. 

• II GUID per un'interfaccia assume il formato TTDJinterfaceName, in cui 
InterfaceName e il nome dell'interfaccia. 

• II GUID per una dispinterface assume il formato DllD_InterfaceName, in cui 
InterfaceName e il nome della dispinterface. 

• II GUID per una CoClass assume il formato CLSID_CZassName, in cui ClassName e 
il nome della CoClass. 

Facendo clic destro nel file sorgente e scegliendo l'opzione Open Source /Header file, 
si vedranno le definizioni seguenti: 

• Dichiarazioni per le CoClasses nella libreria di tipi. Queste mappano ogni CoClass 
alia rispettiva interfaccia predefinita. Inoltre, viene dichiarato un wrapper per 
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ciascuna CoClass, utilizzando il modello TComlnterface. II nome di questo wrapper 
assume il formato CoClassNamePtr. 

• Dichiarazioni per le interfacce e le dispinterface nella libreria di tipi. 

• Dichiarazioni di wrapper di classe per le interfacce e dispinterface. Per le 
interfacce, il wrapper della classe utilizza il modello TComlnterface, e il nome 
assume il formato TComlnterfaceName. Per le dispinterface, il wrapper della 
classe utilizza il modello TAutoDriver, e il cui nome assume il formato 
Interf aceNameDisp . 

• Dichiarazioni per una classe creatore per ciascuna CoClass la cui interfaccia 
predefinita supporti il binding mediante VTable. La classe creatore ha due metodi 
statici, Create e CreateRemote che possono essere utilizzati per istanziare la CoClass 
localmente (Create) oppure in remoto (CreateRemote). Questi metodi restituiscono il 
wrapper della classe per l'interfaccia predefinita della CoClass (definita in 
TypeLibName_TLB.h utilizza il modello TComlnterface. 

• Un wrapper della classe proxy per ogni interfaccia evento.Questo wrapper di 
classe ha un nome che assume il formato TEventsjCoClassName, in cui 
CoClassName e il nome della CoClass che genera gli eventi. La classe proxy 
contiene un elenco di tutti i convogliatori degli eventi dei client e richiama il 
metodo opportuno su tutti i convogliatori di evento appropriati non appena 
l'oggetto server scatena tali eventi. 

Queste dichiarazioni mettono a disposizione tutto cio che occorre per creare istanze 
della CoClass e accedere alia sua interfaccia. Tutto cio che occorre fare e includere il 
file TypeLibName_TLB.h generato nella unit in cui si vuole eseguire il bind a una 
CoClass e chiamarne le interfacce. 

I wrapper delle classi generati utilizzano un oggetto statico (TInitOleT) per gestire 
l'inizializzazione COM. Questo puo essere un problema se si stanno creando oggetti 
da piu thread, in quanto COM viene inizializzato solamente sul primo thread che si 
connette a un server. E necessario creare esplicitamente un'istanza separata di 
TInitOleT o di TInitOle su tutti gli altri thread che si connettono a un server COM. 

Quando si utilizza il Type Library editor o il programma di utilita TLIBIMP viene 
generata anche la unit TypeLibName _TLB. 

Se si vuole utilizzare un controllo ActiveX, oltre alle dichiarazioni descritte in 
precedenza, e necessario avere anche il wrapper della VCL generato. II wrapper della 
VCL si occupa delle problematiche di gestione della finestra del controllo. Nella 
finestra di dialogo Import Type Library dovrebbe essere stato generato anche un 
wrapper VCL per le altre CoClass. Questi wrapper VCL semplificano il compito di 
creare oggetti server e di chiamare i rispettivi metodi. Se ne raccomanda l'uso 
specialmente se si desidera che l'applicazione client risponda agli eventi. 

Le dichiarazioni per i wrapper VCL generati appaiono nella unit TypeLibName_OCX. 
I wrapper di componenti per i controlli ActiveX derivano da TOleControl. I wrapper 
di componenti per gli oggetti Automation derivano da TOleServer. II wrapper di 
componente generato aggiunge le proprieta, gli eventi e i metodi esposti 
dall'interfaccia della CoClass. E possibile utilizzare questo componente come 
qualsiasi altro componente VCL. 
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Non si dovrebbero modificare le unit TypeLibName_TLB o TypeLibNameJDCX 
generate. Esse vengono rigenerate ogni volta che si aggiorna la libreria di tipi e 
pertanto tutte le modifiche vengono sovrascritte. 

Per informazioni piu aggiornate sul codice generato, fare riferimento ai commenti 
nella unit TypeLibName_TLB e nel file utilcls.h generati automaticamente. 



Controllo di un oggetto importato 



Dopo aver importato le informazioni della libreria di tipi, si puo iniziare a 
programmare con gli oggetti importati. II come procedere dipende in parte dagli 
oggetti e in parte dal fatto che si sia scelto o meno di creare wrapper di componenti. 

Uso di wrapper di componenti 



Se e stato generato un wrapper di componente per l'oggetto server, la scrittura 
dell'applicazione client COM non e molto diversa dalla scrittura di una qualsiasi 
altra applicazione contenente componenti VCL. Le proprieta, i metodi e gli eventi 
dell'oggetto server sono gia incapsulati nel componente VCL. Sara sufficiente 
assegnare solamente i gestori di evento, impostare i valori delle proprieta e i metodi 
di chiamata. 

Per utilizzare le proprieta, i metodi e gli eventi dell'oggetto server, consultare la 
documentazione del server. Se possibile, il wrapper del componente fornisce 
automaticamente un'interfaccia duale. C++Builder determina la struttura della 
VTable dalle informazioni nella libreria di tipi. 

Inoltre, il nuovo componente eredita alcune importanti proprieta e metodi dalla sua 
classe base. 

Wrapper ActiveX 

Quando si ospitano controlli ActiveX, si dovrebbe utilizzare sempre un wrapper di 
componente in quanto esso integra la finestra del controllo nel framework della VCL. 

Le proprieta e i metodi che un controllo ActiveX eredita da TOleControl consentono di 
accedere all'interfaccia associata o di ottenere informazioni sul controllo. La maggior 
parte delle applicazioni, comunque, non ha bisogno di utilizzarli. Per contro, si 
utilizzera il controllo importato secondo le stesse modalita usate per un qualsiasi 
altro controllo VCL. 

Di solito, i controlli ActiveX dispongono di una pagina di proprieta che consente di 
impostarne le proprieta. Le pagine di proprieta sono simili agli editor di componenti 
che alcuni componenti visualizzano quando si fa doppio clic su di essi nel Form 
Designer. Per visualizzare la pagina di proprieta di un controllo ActiveX, fare clic 
destro e scegliere l'opzione Properties. 

II modo in cui si utilizza la maggior parte dei controlli ActiveX importati e 
determinato dall'applicazione server. Comunque, i controlli ActiveX utilizzano una 
serie standard di notifiche quando rappresentano i dati di un campo di database. Per 
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informazioni su come utilizzare questi controlli ActiveX, consultare "Uso di controlli 
ActiveX associati ai dati" a pagina 40-9 II modo in cui si utilizza la maggior parte dei 
controlli ActiveX importati e determinato dall'applicazione server. Comunque, i 
controlli ActiveX utilizzano una serie standard di notifiche quando rappresentano i 
dati di un campo di database. Per informazioni su come utilizzare questi controlli 
ActiveX, consultare. 

Wrapper di oggetti Automation 

I wrapper degli oggetti Automation consentono di controllare il modo in cui si 
desidera stabilire la connessione con l'oggetto server: 

• La proprieta ConnectKind indica se il server e locale o remoto e se si desidera 
effettuare la connessione a un server che e gia in esecuzione o ad una nuova 
istanza che dovrebbe essere lanciata. Quando si effettua la connessione a un server 
remoto, si deve specificare il nome della macchina utilizzando la proprieta 

RemoteMachineName. 

• Una volta specificato il tipo di connessione con ConnectKind, esistono tre modi per 
connettere il componente al server: 

• Si puo eseguire la connessione al server in modo esplicito chiamando il metodo 
Connect del componente. 

• Si puo dire al componente di connettersi automaticamente aU'avvio 
deU'applicazione impostando la proprieta AutoConnect a true. 

• Non e necessario eseguire esplicitamente la connessione al server. II 
componente stabilisce automaticamente una connessione non appena si utilizza 
una proprieta o un metodo del server utilizzando il componente. 

Le modalita di chiamata dei metodi o di accesso alle proprieta sono analoghe a quelle 
utilizzate per qualsiasi altro componente: 

TServerComponent 1 - >DoSomething ( ) ; 

La gestione degli eventi e semplice, poiche e possibile utilizzare l'Object Inspector 
per scrivere i gestori di evento. Si noti, tuttavia, che il gestore di evento del 
componente potrebbe avere parametri leggermente diversi da quelli definiti per 
l'evento nella libreria di tipi. Di solito, quei parametri che risultano essere puntatori 
alle interfacce vengono avviluppati utilizzando il modello TComlnterface e non 
appaiono come tipici puntatori alle interfacce. II nome del wrapper di interfaccia 
risultante assume il formato InterfaceNamePtr. 

Per esempio, il codice seguente mostra un gestore di evento per l'evento 
OnNewWorkBook di ExcelApplication. II gestore di evento ha un parametro che 
fornisce l'interfaccia di un'altra CoClass (Excel Workbook). Comunque, l'interfaccia 
non viene passata come un puntatore all'interfaccia di ExcelWorkbook, ma piuttosto 
come un oggetto ExcelWorkbookPtr. 

void _fastcall TForml: :XLappNewWorkbook(TObject *Sender, ExcelWorkbookPtr Wb) 
{ 

ExcelWorkbookl->ConnectTo (Wb) ; 

} 
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In questo esempio, il gestore di evento assegna il workbook a un componente 
ExcelWorkbook, (ExcelWorkbookl). L'esempio mostra come connettere un wrapper 
di componente a un'interfaccia esistente utilizzando il metodo ConnectTo. II metodo 
ConnectTo viene aggiunto al codice generato per il wrapper del componente. 

I server che hanno un oggetto applicazione espongono su quell'oggetto un metodo 
Quit per consentire ai client di terminare la connessione. Quit espone di solito 
funzionalita che sono equivalenti all'utilizzo del menu File per terminare 
l'applicazione. II codice per chiamare il metodo Quit viene generato nel metodo 
Disconnect del componente. Se e possibile chiamare il metodo Quit senza parametri, il 
wrapper del componente ha anche una proprieta AutoQuit. AutoQuit fa in modo che 
il controller chiami il metodo Quit nel momento in cui il componente viene liberato. 
Se si vuole effettuare la disconnessione in un altro momento, oppure se il metodo 
Quit richiede dei parametri, e necessario chiamarlo esplicitamente. Quit appare nel 
componente generato come un metodo pubblico. 

Uso di controlli ActiveX associati ai dati 



Quando si utilizza un controllo ActiveX associato ai dati in un' applicazione 
C++Builder, e necessario associarlo al database di cui ne rappresenta i dati. Per fare 
cio, e necessario un componente data source, esattamente come e necessario un data 
source quando si utilizza un qualsiasi controllo VCL associato ai dati. 

Dopo aver collocato il controllo ActiveX associato ai dati nel Form Designer, 
assegnare la proprieta DataSource alia sorgente dati che rappresenta il dataset 
desiderato. Dopo aver specificato un data source, si puo utilizzare il DataBindings 
editor per collegare la proprieta relativa ai dati di un controllo a un campo del 
dataset. 

Per visualizzare il Data Bindings editor, fare clic destro sul controllo ActiveX 
associato ai dati in modo da visualizzare un elenco di opzioni. Oltre alle opzioni di 
base, apparira anche la voce aggiuntiva Data Bindings. Selezionare l'elemento per 
visualizzare il Data Bindings editor che elenca i nomi dei campi nel dataset e le 
proprieta collegabili del controllo ActiveX. 

Per collegare un campo a una proprieta: 

1 Nella finestra di dialogo Data Bindings Editor di ActiveX, selezionare un campo e 
un nome di proprieta. 

Field Name elenca i campi del database e Property Name elenca le proprieta del 
controllo ActiveX che possono essere collegate a un campo del database. II dispID 
della proprieta e racchiuso tra parentesi, ad esempio Value(12). 

2 Fare clic su Bind e poi su OK. 

Se nella finestra di dialogo non appare alcuna proprieta, significa che il controllo 
ActiveX non contiene proprieta associate ai dati. Per attivare l'associazione di dati 
semplici per una proprieta di un controllo ActiveX, utilizzare la libreria di tipi come 
descritto in "Attivazione dell'associazione di dati semplici con la libreria di tipi" a 
pagina 43-12. 
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L'esempio seguente illustra passo passo l'utilizzo di un controllo ActiveX associato ai 
dati nel contenitore di C++Builder. Questo esempio utilizza il controllo Calendar di 
Microsoft che e disponibile se sul sistema e installato Microsoft Office 97. 

1 Dal menu principale di Delphi, scegliere l'opzione Component I Import ActiveX 
Control. 

2 Selezionare un controllo ActiveX associato ai dati, come Microsoft Calendar 
control 8.0 e modificare il nome della classe in TCalendarAXControl, quindi fare clic 
su Install. 

3 Nella finestra di dialogo Install, fare clic su OK per aggiungere il controllo al 
package utente predefinito rendendo cosi il controllo disponibile sulla Palette. 

4 Scegliere il comando Close All e, successivamente, File I New I Application per 
iniziare una nuova applicazione. 

5 Dalla pagina ActiveX della Component Palette, trascinare sulla scheda un oggetto 
TCalendarAXControl che e stato appena aggiunto alia Palette. 

6 Trascinare sulla scheda un oggetto DataSource dalla pagina Data Access e un 
oggetto Table dalla pagina BDE. 

7 Selezionare l'oggetto DataSource e impostarne la proprieta DataSet a Tablet. 

8 Selezionare l'oggetto Table e fare quanto segue: 

• Impostare la proprieta DatabaseName a BCDEMOS 

• Impostare la proprieta TableName a EMPLOYEE.DB 

• Impostate la proprieta Active a true 

9 Selezionare l'oggetto TCalendarAXControl e impostarne la proprieta DataSource a 
DataSourcel . 

10 Selezionare l'oggetto TCalendarAXControl, fare clic destro e scegliere il comando 
Data Bindings per richiamare il Data Bindings Editor del controllo ActiveX. 

Field Name elenca tutti i campi nel database attivo. Property Name elenca quelle 
proprieta del Controllo ActiveX che sono collegabili ad un campo del database. II 
dispID della proprieta e racchiuso tra parentesi. 

11 Selezionare il campo HireDate e il nome della proprieta Value, scegliere Bind, 
quindi fare clic su OK. 

II nome di campo e la proprieta risultano ora collegati. 

12 Dalla pagina Data Controls, trascinare sulla scheda un oggetto DBGrid e 
impostarne la proprieta DataSource a DataSourcel. 

13 Dalla pagina Data Controls, trascinare sulla scheda un oggetto DBNavigator e 
impostarne la proprieta DataSource a DataSourcel. 

14 Eseguire l'applicazione. 

15 Collaudare l'applicazione come segue: 
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Col campo HireDate visualizzato nell'oggetto DBGrid, spostarsi nel database 
utilizzando l'oggetto Navigator. Le date nel controllo ActiveX dovrebbero 
modificarsi man mano che ci si sposta nel database. 

Esempio: stampa di un documento con Microsoft Word 



La seguenti fasi mostrano come creare un controller Automation che stampa un 
documento usando Microsoft Word 8 da Office 97. 

Prima di iniziare: Creare un nuovo progetto costituito da una scheda, da un pulsante 
e da una finestra di dialogo per l'apertura di file (TOpenDialog). Questi controlli 
costituiscono il controller Automation. 

Fase 1 : preparazione di C++Builder per I'esempio 

Per comodita, C++Builder include nella Component Palette diversi server molto 
comuni, come Word, Excel e PowerPoint. Per dimostrare come si importa un server 
si utilizzera Word.Poiche e gia incluso nella Component palette, la prima cosa da fare 
sara quella di rimuovere il package che contiene Word in modo che sia possibile 
installarlo nuovamente nella tavolozza. La Fase 4 descrive come riportare la 
Component palette alio stato originario. 

Per rimuovere Word dalla Component Palette: 

1 Selezionare il comando Component I Install packages. 

2 Fare clic su Borland C++Builder COM Server Components Sample Package e 
scegliere Remove. 

La pagina Servers della Component palette non conterra piu nessuno dei server 
forniti con C++Builder. (Se non sono stati importati altri server, anche la pagina 
Servers sara rimossa.) 

Fase 2: importazione della libreria di tipi di Word 

Per importare la libreria di tipi di Word: 

1 Scegliere il comando Project I Import Type Library. 

2 Nella finestra di dialogo Import Type Library, 

1 Selezionare Microsoft Office 8.0 Object Library. 

Se Word (Versione 8) non e incluso nell'elenco, fare clic sul pulsante Add, 
passare alia directory ProgrammiX Microsoft Office \ Office, selezionare il file 
della libreria di tipi di Word, MSWord8.olb, fare clic su Add e selezionare 
finalmente Word (Versione 8) dall'elenco. 

2 Per l'opzione Palette Page, selezionare Servers. 

3 Fare clic su Install. 

Apparira la finestra di dialogo Install. Selezionare la pagina Into New Packages 
e scrivere WordExample per creare un nuovo package che conterra la libreria di 
tipi selezionata. 
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3 Selezionare la pagina Servers della Component Palette, selezionare 
WordApplication e collocarlo su una scheda. 

4 Scrivere un gestore di evento per l'oggetto pulsante come descritto nel paragrafo 
successive 

Fase 3: uso di un oggetto interfaccia VTable o dispatch per il controllo di 
Microsoft Word 

Per controllare Microsoft Word, e possibile usare uno dei due oggetti seguenti. 

Uso di un oggetto interfaccia VTable 

Trascinando sulla scheda un'istanza dell'oggetto WordApplication sara possibile 
accedere in modo molto semplice al controllo utilizzando un oggetto interfaccia 
VTable. Sara sufficiente chiamare i metodi della classe appena creata. Nel caso di 
Word, questa e la classe TW 'or -d Application. 

1 Selezionare il pulsante, fare doppio clic sul suo gestore di eventi OnClick e scrivere 
il seguente codice di gestione dell'evento: 

void __fastcall TForml: :ButtonlClick(TObject *Sender) 
{ 

if (OpenDialogl->Execute() ) 
{ 

TVariant FileName = OpenDialogl->FileName.c_str() ; 
WordApplicationl->Documents->Open(&FileName) ; 

WordApplicationl->ActiveDocument->PrintOut () ; 

} 

} 

2 Compilare ed eseguire il programma. Facendo clic sul pulsante, Word richiedera 
un file da stampare. 

Uso di un oggetto interfaccia dispatch 

Come metodo alternative e possibile utilizzare un'interfaccia dispatch per il bind 
differito. Per utilizzare un'oggetto interfaccia dispatch, si deve creare e inizializzare 
l'oggetto Application utilizzando la classe wrapper dispatch _ApplicationDisp nel 
modo seguente. Si noti che i metodi della dispinterface sono "documentati" nel 
sorgente come interfacce VTable restituite, ma, in effetti, e necessario eseguirne una 
conversione di tipo trasformandole in interfacce dispatch. 

1 Selezionare il pulsante, fare doppio clic sul suo gestore di eventi OnClick e scrivere 
il seguente codice di gestione dell'evento: 

void __fastcall TForml: :ButtonlClick(TObject *Sender) 
{ 

if (OpenDialogl->Execute() ) 
{ 

TVariant FileName = OpenDialogl->FileName.c_str() ; 

_ApplicationDisp MyWord; 
MyWord.Bind(CLSID_WordApplication) ; 
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DocumentsDisp MyDocs = MyWord->Docuraents ; 
MyDocs->Open (SFileName) ; 

_DocumentDisp MyActiveDoc = MyWord->ActiveDocument ; 

MyActiveDoc->PrintOut ( ) ; 

MyWord->Quit(); 

} 

2 Compilare ed eseguire il programma. Facendo clic sul pulsante, Word richiedera 
un file da stampare. 

Fase 4: ripristino dello stato originario 

Dopo aver completato questa esercitazione, e consigliabile ripristinare lo stato 
originario di C++Builder. 

1 Cancellare gli oggetti sulla pagina Servers: 

• Scegliere il comando Component I Install Packages. 

• Selezionare nell'elenco il package WordExample e fare clic per rimuoverlo. 

• Fare clic su Yes per confermare l'operazione. 

• Uscire dalla finestra di dialogo Install Packages facendo clic su OK. 

2 Ripristinare il Borland C++Builder COM Server Components Sample Package: 

• Scegliere il comando Component I Install Packages. 

• Fare clic sul pulsante Add. 

• Nella finestra di dialogo attivata, scegliere bcb97axserver60.bpl per i 
componenti Office 97, o bcb2kaxserver60.bpl per i componenti Office 2000. 

• Uscire dalla finestra di dialogo Install Packages facendo clic su OK. 

Scrittura del codice del client in base alle definizioni della libreria di 
tipi 



Sebbene sia necessario utilizzare un wrapper di componenti per ospitare un controllo 
ActiveX, e possibile scrivere un Automation controller utilizzando solamente le 
definizioni della libreria di tipi che appaiono nella unit TypeLibName_TLB. Questo 
procedimento e un po' piu complesso se paragonato a quello che affida tutte le 
operazioni al componente, specialmente se c'e la necessita di rispondere agli eventi. 

Connessione a un server 

Prima di poter pilotare un Automation server mediante un'applicazione controller, e 
necessario ottenere un riferimento ad una delle interfacce che esso supporta. 
Solitamente si effettua una connessione a un server mediante la sua interfaccia 
principale. Per esempio, ci si connettete a Microsoft Word tramite il componente 
WordApplication. 

Se l'interfaccia principale e un'interfaccia duale, e possibile utilizzare l'oggetto 
creatore nel file TypeLibName_TLB.h. Le classi creatore hanno lo stesso nome della 
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CoClass, col in piu il prefisso "Co". E possibile effettuare una connessione a un server 
sulla stessa macchina chiamando il metodo Create, oppure a un server su una 
macchina remota utilizzando il metodo CreateRemote. Poiche Create e CreateRemote 
sono metodi statici, per poterli chiamare non e necessaria un'istanza della classe 
creatore. 

plnterface = CoServerClassName. Create () ; 

plnterface = CoServerClassName. CreateRemote ( "Machinel" ) ; 

Create e CreateRemote restituiscono il wrapper della classe per l'interfaccia predefinita 
della CoClass (definita in TypeLibNameJTLB.h utilizzando il modello TComlnterface. 

Se l'interfaccia predefinita e un'interfaccia dispatch, non e stata generata alcuna 
classe Creator per la CoClass. Occorre invece creare un'istanza della classe del 
wrapper generata automaticamente per l'interfaccia predefinita. Questa classe e 
definita utilizzando il modello TAutoDriver, ed il suo nome assume il formato 
InterfaceNameDisp. In seguito, chiamate il metodo Bind passandogli il GUID della 
CoClass (all'inizio della unit _TLB viene definita una costante per questo GUID). 

Controllo di un server Automation usando un'interfaccia duale 

Dopo avere utilizzato la classe creatore generata automaticamente per connettersi al 
server, si chiamano i metodi dell'oggetto wrapper dell'interfaccia, utilizzando 
l'operatore "->". Ad esempio: 

TComApplication AppPtr = CoWordApplication_ .Create () ; 
AppPtr->DoSomething; 

II wrapper dell'interfaccia e classe creatore sono definite nella unit 
TypeLibNameJTLB, generata automaticamente al momento dell'importazione della 
libreria di tipi. Uno dei vantaggi derivanti dall'utilizzo di questa classe wrapper per 
le interfacce e che libera automaticamente l'interfaccia associata al momento della 
sua distruzione. 

Per informazioni sulle interfacce duali, consultare "Interfacce duali" a pagina 41-13. 

Controllo di un server Automation usando un'interfaccia dispatch 

Di solito, per controllare un Automation server si utilizzera l'interfaccia duale, come 
descritto in precedenza. Tuttavia, potrebbe sorgere la necessita di controllare un 
Automation server mediante un'interfaccia dispatch perche non e disponibile 
un'interfaccia duale. 

Per chiamare i metodi di un'interfaccia dispatch: 

1 Connettersi al server utilizzando il metodo Bind della classe wrapper 
dell'interfaccia dispatch. Per maggiori informazioni sulla connessione al server, 
consultare "Connessione a un server" a pagina 40-13. 

2 Controllare l'Automation server chiamando i metodi dell'oggetto wrapper 
dell'interfaccia dispatch. 

La classe wrapper rende evidenti le proprieta e i metodi dell'interfaccia dispatch 
sotto forma di sue proprieta e metodi. Inoltre, poiche deriva da TAutoDriver, e 
possibile utilizzare il meccanismo IDispatch per chiamare le proprieta e i metodi 
dell'oggetto server. Prima di poter accedere a proprieta o metodi, e necessario 
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ottenerne l'ID di dispatch. Per fare cio, utilizzare il metodo GetlDsOfNames, 
passandogli un nome e un riferimento a una variabile DISPID che ricevera l'ID di 
dispatch per quel nome. Una volta ottenuto l'ID di dispatch, e possibile utilizzarlo 
per chiamare OlePropertyGet, OlePropertyPut o OleFunction per accedere alle proprieta 
e ai metodi degli oggetti server. 

Un altro modo per utilizzare le interfacce dispatch e quello di assegnarle a un Variant. 
Questo metodo e richiesto da alcuni oggetti VCL per quelle proprieta o parametri il 
cui valori sono interfacce. II tipo Variant include un supporto interno per chiamare le 
interfacce dispatch, tramite i suoi metodi OlePropertyGet, OlePropertySet, OleFunction 
e OleProcedure, che corrispondono ai metodi su una classe wrapper di un'interfaccia 
dispatch. L'utilizzo di un Variant puo essere un po' piu lento rispetto all'utilizzo della 
classe wrapper di un'interfaccia dispatch, in quanto i metodi Variant cercano 
dinamicamente l'ID di dispatch ogni volta che li si chiama.Comunque, hanno il 
vantaggio che non e necessario importare una libreria di tipi per utilizzarli. 

Occorre prestare attenzione quando si assegna un'interfaccia a un Variant invece che 
a un wrapper di interfaccia dispatch. Mentre il wrapper gestisce automaticamente le 
chiamate a AddRefe a Release, il Variant non lo fa. Cosi, per esempio, se si assegna a 
un wrapper di interfaccia un Variant il cui valore e un'interfaccia, il wrapper di 
interfaccia non chiama AddRef, ma il suo distruttore chiama Release. A causa di cio, 
non si consiglia l'utilizzo di Variant se non nel caso in cui appaiano gia come 
proprieta di un oggetto VCL. 

Per maggiori informazioni sulle interfacce dispatch, consultare "Interfacce di 
Automation" a pagina 41-13. 

Gestione degli eventi in un controller Automation 

Quando si genera un wrapper di componenti per un oggetto di cui si importa la 
libreria di tipi, e possibile rispondere agli eventi utilizzando semplicemente gli eventi 
aggiunti al componente generate Se non si utilizza un wrapper di componenti (o se il 
server utilizza eventi COM+), e necessario scrivere personalmente un convogliatore 
di eventi. 

Gestione da programma degli eventi di Automation 

Prima di poter gestire gli eventi, e necessario definire un convogliatore di eventi. 
Questa e una classe che implementa l'interfaccia dispatch degli eventi, definita nella 
libreria di tipi del server. 

II convogliatore di eventi e un discendente di TEventDispatcher, che e una classe 
basata su un modello che richiede due parametri, la classe del convogliatore di eventi 
e il GUID dell'interfaccia dell'evento gestita dal convogliatore di eventi: 

class MyEventSinkClass : TEventDispatcher<MyEventSinkClass , DIID_TheServerEvents> 
{ 

...// declare the methods of DHD_TheServerEvents here 
} 

Una volta ottenuta un'istanza della classe convogliatore di eventi, chiamarne il 
metodo ConnectEvents per rendere nota al server l'esistenza del convogliatore di 
eventi. Questo metodo utilizza le interfacce IConnectionPointContainer e 
IConnectionPoint del server per registrare l'oggetto come un convogliatore di eventi. 
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A questo punto l'oggetto riceve le chiamate dal server non appena si verifica un 
evento: 

plnterface = CoServerClassName .CreateReraote ( "Machinel" ) ; 
MyEventSinkClass ES; 
ES.ConnectEvents (plnterface) ; 

Prima di poter liberare il convogliatore di eventi si deve terminare la connessione. 
Per fare cio, chiamare il metodo DisconnectEvents del convogliatore di eventi: 

ES .DisconnectEvents (plnterface) ; 

Occorre essere certi che il server abbia rilasciato la sua connessione al convogliatore 
di eventi prima di poterlo liberare. Poiche non si sa come il server risponde alia 
notifica di disconnessione iniziata da DisconnectEvents, cio potrebbe trasformarsi in 
una specie di gara se si libera il convogliatore di eventi immediatamente dopo la 
chiamata. TEventDispatcher evita automaticamente questa situazione mantenendo un 
proprio contatore dei riferimenti che non viene decrementato finche il server non 
rilascia l'interfaccia del convogliatore di eventi. 

Gestione di eventi COM+ 

In ambiente COM+, i server utilizzano uno speciale oggetto helper per generare 
eventi invece di un set di interfacce speciali (IConnectionPointContainer e 
IConnectionPoint). A causa di cio, non e possibile utilizzare un convogliatore di eventi 
che discende da TEventDispatcher. TEventDispatcher e progettato per lavorare con 
quelle interfacce e non con oggetti evento di COM+. 

Invece di definire un convogliatore di eventi, l'applicazione client definisce un 
oggetto subscriber. Gli oggetti subscriber obietta, come i convogliatori di eventi, 
forniscono l'implementazione dell'interfaccia dell'evento. Differiscono dai 
convogliatori di eventi per il fatto che si "abbonano" ad un particolare oggetto evento 
piuttosto che connettersi a un punto di connessione di un server. 

Per definire un oggetto subscriber, utilizzare il COM Object wizard, selezionando 
l'interfaccia dell'oggetto evento come quella che si desidera implementare. II wizard 
genera una unit di implementazione con l'abbozzo dei metodi che si dovranno 
completare per creare i gestori di evento. Per ulteriori informazioni sull'utilizzo del 
COM Object wizard per implementare un'interfaccia esistente, consultare "Utilizzo 
di COM object wizard" a pagina 41-3. 

Potrebbe essere necessario aggiungere l'interfaccia dell'oggetto evento al file di 
registro utilizzando il wizard, nel caso non appaia nell'elenco delle interfacce che e 
possibile implementare. 

Una volta creato l'oggetto subscriber, si deve effettuare la sottoscrizione 
all'interfaccia dell'oggetto evento o ai singoli metodi (gli eventi) su quella interfaccia. 
Esistono tre tipi di sottoscrizioni fra cui scegliere: 

• Sottoscrizioni transitorie. Analogamente ai convogliatori di evento tradizionali, le 
sottoscrizioni transitorie sono legate alia durata di un'istanza dell'oggetto. 
Quando l'oggetto subscriber viene liberato, la sottoscrizione termina e COM+ non 
gli spedisce piu alcun evento. 
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• Sottoscrizioni permanenti. Queste sono legate alia classe dell'oggetto invece che a 
un'istanza specifica dell'oggetto. Quando l'evento si verifica, COM individua o 
avvia un'istanza dell'oggetto subscriber e ne chiama il gestore di evento. Gli 
oggetti in-process (DLL) utilizzano questo tipo di sottoscrizione. 

• Sottoscrizioni per-utente. Queste sottoscrizioni rappresentano una versione piu 
sicura delle sottoscrizioni transitorie. Sia l'oggetto subscriber sia l'oggetto server 
che scatena gli eventi, devono essere in esecuzione nello stesso account di utente 
sulla stessa macchina. 

Per effettuare la sottoscrizione a un oggetto evento, utilizzare la funzione globale 
RegisterComPlusEventSubscription. 

Gli oggetti che effettuano una sottoscrizione a eventi COM+ devono essere installati 
in un'applicazione di COM+. 

Creazione di client per server che non hanno una libreria di tipi 



Alcune vecchie tecnologie COM, come ad esempio OLE (object linking and 
embedding), non forniscono informazioni di tipo in una libreria di tipi. Esse si 
appoggiano invece ad una serie standard di interfacce predefinite. Per scrivere client 
in grado di ospitare tali oggetti, e possibile utilizzare il componente TOleContainer. 
Questo componente e presente sulla pagina System della Component palette. 

TOleContainer si comporta come sito ospitante per un oggetto 01e2. Implementa 
l'interfaccia IOleCUentSite e, facoltativamente, IOleDocumentSite. La comunicazione 
viene gestita utilizzando verbi OLE. 

Per utilizzare TOleContainer: 

1 Collocare un componente TOleContainer sulla scheda. 

2 Impostare a true la proprieta AllowActiveDoc se si desidera ospitare un Active 
document. 

3 Impostare la proprieta AllowInPlace per indicare se l'oggetto ospitato deve 
apparire nel TOleContainer o in una finestra separata. 

4 Scrivete i gestori di evento per rispondere all'attivazione, alia disattivazione, alio 
spostamento o al ridimensionamento dell'oggetto. 

5 Per eseguire il bind dell'oggetto TOleContainer in fase di progetto, fare clic destro e 
scegliere il comando Insert Object. Nella finestra di dialogo Insert Object, scegliere 
un oggetto server da ospitare. 

6 Per eseguire il bind dell'oggetto TOleContainer in fase esecuzione, esistono molti 
metodi fra cui scegliere, a seconda di come si desidera identificare l'oggetto server. 
Fra questi vi sono CreateObject, che richiede un id di programma, 
CreateObjectFromFile, che richiede il nome di un file in cui e stato salvato l'oggetto, 
CreateObjectFromlnfo, che richiede un struct contenente informazioni su come 
creare l'oggetto, oppure CreateLinkToFile, che richiede il nome di un file in cui e 
stato salvato l'oggetto e a cui si collega invece che incorporarlo. 
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7 Una volta collegato l'oggetto, e possibile accedere alia sua interfaccia 
utilizzando la proprieta OleObjectlnterface. Tuttavia, poiche la comunicazione 
con gli oggetti 01e2 era basata su verbi OLE, molto piu probabilmente si 
trasmetteranno comandi al server utilizzando il metodo DoVerb. 

8 Quando si desidera rilasciare l'oggetto server, chiamare il metodo 
DestroyObject. 
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Capitolo 




Creazione di semplici server COM 



C++Builder fornisce wizard che facilitano la creazione di diversi oggetti COM. Gli 
oggetti COM piu semplici sono server che mettono a disposizione proprieta e metodi 
(e possibilmente eventi) attraverso un'interfaccia predefinita che puo essere chiamata 
dai client. 

Server COM e Automation non sono disponibili per l'uso in applicazioni CLX. 
Questa tecnologia e da utilizzare solo in ambiente Windows e non e per 
multip iattaf or ma . 

Due wizard, in particolare, facilitano il processo di creazione di semplici oggetti 
COM: 

• COM Object wizard costruisce un oggetto COM leggero la cui interfaccia 
predefinita deriva da IUnknown o che implementa un'interfaccia gia registrata nel 
sistema. Questa procedura guidata fornisce il livello di flessibilita massimo nei tipi 
di oggetti COM che e possibile creare. 

• Automation Object wizard crea un semplice oggetto Automation la cui interfaccia 
predefinita deriva da IDispatch. IDispatch introduce un meccanismo standard di 
marshaling e supporta il binding differito delle chiamate di interfaccia. 

COM definisce molte interfacce e meccanismi standard per la gestione di situazioni 
specifiche. I wizard di C++Builder automatizzano la maggior parte delle attivita piu 
comuni. Tuttavia, alcune attivita, come il marshaling personalizzato, non sono 
supportate da alcuna procedura guidata di C++Builder. Per informazioni su questa e 
altre tecnologie non esplicitamente supportate da C++Builder, fare riferimento alia 
documentazione di Microsoft Developer's Network (MSDN). Anche il sito Web di 
Microsoft fornisce informazioni aggiornate sul supporto COM. 
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Panoramica sulla creazione di un oggetto COM 



Automation object wizard, per la creazione di un nuovo server di automazione, e 
COM object wizard, per la creazione di altri tipi di oggetto COM, sono caratterizzati 
dallo svolgimento dello stesso processo. Di seguito sono descritte le varie fasi: 

1 Progettazione dell'oggetto COM. 

2 Uso di COM Object wizard o Automation Object wizard per creare l'oggetto 
server. 

3 Specifica delle opzioni nella pagina ATL della finestra di dialogo delle opzioni di 
progetto per indicare in che modo l'oggetto COM chiamera l'applicazione che 
ospita l'oggetto e quale tipo di supporto di debugging si desidera. 

4 Definizione dell'interfaccia che l'oggetto mostra ai client. 

5 Registrazione dell'oggetto. 

6 Collaudo e debug dell'applicazione. 

Progettazione di un oggetto COM 



Quando si progetta l'oggetto COM, bisogna decidere quale interfaccia si intende 
implementare. E possibile scrivere un oggetto COM per implementare un'interfaccia 
che e gia stata definita, oppure e possibile definire una nuova interfaccia che 
l'oggetto deve implementare. Inoltre, e possibile fare in modo che l'oggetto supporti 
piu di un'interfaccia. Per informazioni sulle interfacce COM standard che e possibile 
supportare, consultare la documentazione di MSDN. 

• Per creare un oggetto COM che implementa un'interfaccia esistente, utilizzare 
COM Object wizard. 

• Per creare un oggetto COM che implementa una nuova interfaccia da definire, 
utilizzare COM Object wizard o Automation Object wizard. COM object wizard 
pud generare una nuova interfaccia predefinita che deriva da IUnknown, e 
Automation object wizard fornisce all'oggetto un'interfaccia predefinita che 
deriva da IDispatch. Indipendentemente dalla procedura guidata scelta e sempre 
possibile utilizzare successivamente il Type Library editor per modificare 
l'interfaccia genitore o quella predefinita generata dalla procedura guidata. 

Oltre a decidere quali interfacce supportare, si deve stabilire l'oggetto COM se e 
destinato ad essere un server in-process un server out-of-process o un server remote 
Per tutti questi tipi di server, comunque, il ricorso ad una libreria di tipi COM fa si 
che i dati vengano disposti automaticamente. Altrimenti, si deve prendere in 
considerazione come disporre i dati nei server esterni al processo. Per informazioni 
sugli altri tipi di server, consultare il paragrafo, "Server in-process, out-of-process e 
remoti", a pagina 38-6. 
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Utilizzo di COM object wizard 



II COM object wizard esegue le seguenti operazioni: 

• Crea una nuova unit. 

• Definisce una nuova classe che deriva dalle classi ATL CComObjectRootEx e 
CComCoClass. Per maggiori informazioni sulle classi di base, vedere "Codice 
generato dai wizard" a pagina 38-23. 

• Aggiunge una libreria di tipi al progetto e vi aggiunge l'oggetto e la relativa 
interfaccia. 

Prima di creare un oggetto COM, bisogna creare o aprire il progetto per 
l'applicazione che contenga la funzionalita che si intende implementare. II progetto 
puo essere un'applicazione o una libreria ActiveX, in base alle proprie necessita. 

Per richiamare COM object wizard: 

1 Scegliere File I New I Other per aprire la finestra di dialogo New Items. 

2 Selezionate la pagina identificata con ActiveX. 

3 Fare doppio clic sull'icona COM object. 
Nel wizard si deve specificare quanto segue: 

• Nome della CoClass: questo e il nome dell'oggetto cosi come viene visualizzato ai 
client. La classe creata per implementare l'oggetto ha questo nome preceduto da 
una lettera "T". Se si sceglie di non implementare un'interfaccia esistente, il 
wizard assegna alia CoClass un'interfaccia predefinita che ha questo nome 
preceduto da una lettera T. 

• Interfaccia da implementare: come impostazione predefinita, il wizard assegna 
all'oggetto un'interfaccia predefinita che deriva da IUnknown. Dopo l'uscita dal 
wizard, e possibile utilizzare il Type Libary editor per aggiungere a questa 
interfaccia proprieta e metodi. Tuttavia, e anche possibile selezionare 
un'interfaccia predefinita da implementare nell'oggetto. Fare clic sul pulsante List 
in COM object wizard per richiamare l'lnterface Selection wizard, dove e possibile 
selezionare qualsiasi interfaccia duale o personalizzata def inita in una libreria di 
tipi registrata nel sistema. L'interfaccia che si seleziona diventa quella predefinita 
per la nuova CoClass. II wizard aggiunge tutti i metodi presenti in questa 
interfaccia alia classe di implementazione generata, quindi e necessario solamente 
compilare il corpo dei metodi nella unit di implementazione. Notare che se si 
seleziona un'interfaccia esistente, questa non viene aggiunta alia libreria di tipi del 
progetto. Questo significa che quando si sviluppa l'oggetto e necessario anche 
impiegare la libreria di tipi che definisce l'interfaccia. 

• Modello di threading: tipicamente, le richieste del client all'oggetto entrano in 
thread di esecuzione diversi. E possibile specificare il modo in cui COM serializza 
questi thread quando chiama l'oggetto. La scelta del modello di threading 
determina come vengono registrati gli oggetti. II programmatore e responsabile di 
fornire ogni supporto di threading necessario per il modello scelto. Per 
informazioni sulle differenti possibility, vedere "Scelta di una modello di 
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threadingl" a pagina 41-5. Per informazioni su come fornire supporto thread 
all'applicazione, vedere il Capitolo 11, "Scrittura di applicazioni multi-thread". 

• Supporto degli eventi: e necessario indicare se si desidera che l'oggetto generi 
eventi a cui i client possono rispondere. II wizard pud fornire supporto per le 
interfacce necessarie per la generazione di eventi e lo smistamento di chiamate ai 
gestori di eventi client. Per informazioni sul funzionamento degli eventi e su cio 
che e necessario per la loro implementazione, vedere "Esposizione di eventi ai 
client" a pagina 41-11. 

• Oleautomation: se l'intenzione e quella di limitarsi all'uso di tipi compatibili con 
Automation, e possibile lasciare che COM gestisca automaticamente il marshaling 
quando non si genera un server in-process. Contrassegnando l'interfaccia 
dell'oggetto come OleAutomation nella libreria di tipi, si abilita COM a 
configurare automaticamente i proxy e gli stub e a gestire il passaggio dei 
parametri attraverso i confini del processo. Per maggiori informazioni su questo 
processo, vedere "II meccanismo di smistamento" a pagina 38-8. Se si sta 
generando una nuova interfaccia e possibile specificare solo se essa e compatibile 
con Automation. Se si sta generando una nuova interfaccia e possibile specificare 
solo se essa e compatibile con Automation. Se si seleziona un'interfaccia esistente, 
i suoi attributi sono gia specificati nella relativa libreria di tipi. Se l'interfaccia 
dell'oggetto non e contrassegnata come OleAutomation, e necessario creare un 
server in-process oppure scrivere del proprio codice per il marshaling. 

• Implement Ancestor Interfaces: Scegliere questa opzione se si desidera che il 
wizard generi automaticamente le routine prototipo per le interfacce ereditate. Vi 
sono tre interfacce ereditate che non saranno mai implementate dal wizard: 
IUnknown, IDispatch e IAppServer. IUnknown e IDispatch non vengono 
implementate in quanto, per queste due interfacce, ATL fornisce la propria 
implementazione. IAppServer non viene implementato in quanto viene 
implementato automaticamente quando si opera con i dataset client e con i 
provider di dataset. 

E possibile aggiungere opzionalmente una descrizione dell'oggetto COM. Questa 
descrizione viene visualizzata nella libreria di tipi per l'oggetto. 

Uso di Automation object wizard 



The Automation object wizard svolge le seguenti operazioni: 

• Crea una nuova unit. 

• Definisce una nuova classe che deriva dalle classi ATL CComObjectRootEx e 
CComCoClass. Per maggiori informazioni sulle classi di base, vedere "Codice 
generato dai wizard" a pagina 38-23. 

• Aggiunge una libreria di tipi al progetto e vi aggiunge l'oggetto e la relativa 
interfaccia. 

Prima di creare un oggetto Automation, creare o aprire il progetto per 
un'applicazione contenente le funzionalita da mettere a disposizione. II progetto puo 
essere un'applicazione o una libreria ActiveX, in base alle proprie necessita. 
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Per visualizzare Automation wizard: 

1 Scegliere il comando File I New I Other. 

2 Selezionate la pagina identificata con ActiveX. 

3 Fare doppio clic sull'icona Automation Object. 

Nella finestra di dialogo del wizard, specificare le seguenti informazioni: 

• Nome della CoClass: questo e il nome dell'oggetto cosi come viene visualizzato ai 
client. L'interfaccia predefinita dell'oggetto viene creata con un nome basato su 
quello di questa CoClass preceduto da una lettera T, e la classe creata per 
implementare l'oggetto ha questo nome preceduto da una lettera T. 

• Modello di threading: tipicamente, le richieste del client all'oggetto entrano in 
thread di esecuzione diversi. E possibile specificare il modo in cui COM serializza 
questi thread quando chiama l'oggetto. La scelta del modello di threading 
determina come vengono registrati gli oggetti. II programmatore e responsabile di 
fornire ogni supporto di threading necessario per il modello scelto. Per 
informazioni sulle differenti possibility, vedere "Scelta di una modello di 
threadingl" a pagina 41-5. Per informazioni su come fornire supporto thread 
all'applicazione, vedere il Capitolo 11, "Scrittura di applicazioni multi-thread". 

• Supporto degli eventi: e necessario indicare se si desidera che l'oggetto generi 
eventi a cui i client possono rispondere. II wizard puo fornire supporto per le 
interfacce necessarie per la generazione di eventi e lo smistamento di chiamate ai 
gestori di eventi client. Per informazioni sul funzionamento degli eventi e su cio 
che e necessario per la loro implementazione, vedere "Esposizione di eventi ai 
client" a pagina 41-11. 

E possibile aggiungere opzionalmente una descrizione dell'oggetto COM. Questa 
descrizione viene visualizzata nella libreria di tipi per l'oggetto. 

L'oggetto Automation implementa un'interf accia duale, che supporta il binding 
anticipato (fase di compilazione) attraverso VTable e il binding differito (fase di 
esecuzione) attraverso l'interfaccia IDispatch. Per maggiori informazioni, vedere 
"Interfacce duali" a pagina 41-13. 

Scelta di una modello di threadingl 



Quando si crea un oggetto usando un wizard, si seleziona un modello di threading 
che l'oggetto puo supportare. Aggiungendo il supporto dei thread all'oggetto COM, 
se ne migliorano le prestazioni, perche i client multipli possono accedere 
all'applicazione contemporaneamente. 



Creazione di semplici server COM 41-5 



Uso di Automation object wizard 



La Tabella 41.1 elenca i diversi modelli di threading che e possibile specificare. 



Tabella 41.1 Modelli di threading per gli oggetti COM 
Modello di threading Descrizione 



Singolo 



Apartment (or Single- 
threaded apartment) 



Free (definite, anche 

multi-threaded 

apartment) 



Both 



Neutral 



II server non fornisce alcun 
supporto dei thread. COM 
serializza le richieste dei client in 
modo che l'applicazione ne riceva 
una alia volta. 



COM assicura che solo un thread 
client alia volta possa chiamare 
l'oggetto. Tutte le chiamate dei 
client utilizzano il thread in cui e 
stato creato l'oggetto. 



Gli oggetti possono ricevere 
chiamate da qualsiasi numero di 
thread alia volta. 



L'opzione e analoga al modello 
Free-threaded con la differenza 
che le chiamate in uscita (ad 
esempio, le callback) vengono 
sempre eseguite nello stesso 
thread. 

Piu client possono chiamare 
contemporaneamente l'oggetto su 
thread differenti, ma COM 
assicura che non vi siano due 
chiamate in conflitto. 



Pro e contro dell'implementazione 

I client vengono gestiti 
singolarmente, e pertanto non e 
necessario il supporto di alcun 
thread. 

Non ci sono vantaggi a livello di 
prestazioni. 

Gli oggetti possono accedere in 
modo sicuro ai relativi dati di 
istanza, ma i dati globali devono 
essere protetti utilizzando le 
sezioni critiche o qualche altra 
forma di serializzazione. 

Le variabili locali del thread sono 
affidabili per piu chiamate. 

C'e qualche vantaggio a livello di 
prestazioni. 

Gli oggetti devono proteggere tutte 
le istanze e i dati globali usando le 
sezioni critiche o qualche altra 
forma di serializzazione. 

Le variabili locali del thread non 
sono affidabili per piu chiamate. 

Massime prestazioni e flessibilita. 

Non richiede che l'applicazione 
fornisca il supporto dei thread per i 
parametri forniti alle chiamate in 
uscita. 

E necessario proteggersi dai 
conflitti di thread che coinvolgono 
dati globali e da qualsiasi dato di 
istanza a cui accedono piu metodi. 

Questo modello non va usato con 
oggetti che hanno un'interfaccia 
utente (controlli visuali). 

Questo modello e disponibile solo 
in COM+. Sotto COM, viene 
mappato sul modello Apartment. 



Le variabili locali (tranne quelle nelle callback) sono sempre sicure, 
indipendentemente dal modello di threading. La ragione e che le variabili locali sono 
memorizzate nello stack e ciascun thread ha il proprio stack. Le variabili locali 
possono non essere sicure nelle callback quando si utilizza il threading free. 

II modello di threading scelto nel wizard determina come viene registrato l'oggetto 
nel Registry di sistema. Bisogna accertarsi che l'implementazione dell'oggetto 
aderisca al modello di threading che e stato scelto. Per informazioni generali sulla 
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scrittura di codice thread sicuro, consul tare il Capitolo 11, "Scrittura di applicazioni 
multi-thread". 

Affinche COM chiami l'oggetto in base al modello di threading specificato, e 
necessario che venga inizializzato il supporto per quel tipo di modello. E possibile 
specificare come viene inizializzato COM tramite la pagina ATL della finestra di 
dialogo di opzioni del progetto. 

Per server in-process, l'impostazione del modello di threading nel wizard definisce la 
chiave del modello di threading sulla voce di registro CLSID. 

I server a processo esterno vengono registrati come EXE, e COM deve essere 
inizializzato per il modello di threading piu alto necessario. Ad esempio, se un EXE 
include un oggetto con threading free, deve essere inizializzato per tale modello, e 
cio significa che puo fornire il supporto previsto per qualsiasi oggetto con threading 
free o apartment contenuto nell'EXE. Per specificare in che modo COM viene 
inizializzato, utilizzare la pagina ATL della finestra di dialogo di opzioni del 
progetto. 

Scrittura di un oggetto che supports il modello free threading 

Utilizzare il modello di threading free (o entrambi) invece di quello apartment 
quando e necessario che piu di un thread possa accedere all'oggetto. Un esempio 
comune e un'applicazione client connessa ad un oggetto su una macchina remota. 
Quando il client remoto chiama un metodo di quell'oggetto, il server riceve la 
chiamata su un thread da un insieme di thread della macchina server. Questo thread 
ricevente effettua la chiamata a livello locale all'oggetto vero e proprio; e, dal 
momento che l'oggetto supporta il modello di threading free, il thread puo effettuare 
una chiamata diretta nell'oggetto. 

Se, invece, l'oggetto supportasse il modello di threading apartment, la chiamata 
dovrebbe essere trasferita al thread sul quale l'oggetto e stato creato, e il risultato 
sarebbe ritrasferito al thread ricevente prima di ritornare al client. Questo approccio 
richiede un ulteriore smistamento. 

Per supportare il threading free, occorrono considerare il modo in cui e possibile 
accedere ai dati dell'istanza per ciascun metodo. Se il metodo e la scrittura nei dati 
dell'istanza, per proteggere i dati dell'istanza si devono utilizzare le sezioni critiche o 
qualche altra forma di serializzazione. Probabilmente, l'overhead delle chiamate 
critiche di serializzazione e minore dell'esecuzione del codice di smistamento di 
COM. 

Si noti che, se i dati dell'istanza sono a sola lettura, la serializzazione non e 
necessaria. 

I server in-process free-threaded possono migliorare le prestazioni agendo come 
oggetto esterno un'aggregazione con il gestore del marshaling free-threaded. 
Quest'ultimo fornisce una scorciatoia per la gestione dei thread standard di COM 
quando viene chiamata una DLL free threaded da parte di un host (client) che non e 
free threaded. 

Per eseguire l'aggregazione con il gestore di marshaling free threaded, e necessario 
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• Chiamare CoCreateFreeThreadedMarshaler, passando l'interfaccia IUnknown 
dell'oggetto per il gestore di marshaling free threaded da utilizzare: 

CoCreateFreeThreadedMarshaler (static_cast<lUnknown *>(this) , SFMarshaler) ; 

Questa riga assegna all'interfaccia per il gestore di marshaling free threaded un 
numero di classe, FMarshaler. 

• Tramite il Type Libary editor, aggiungere l'interfaccia IMarshal al set di interfacce 
implementate da CoClass. 

• Nel metodo Querylnterface dell'oggetto, delegare le chiamate per IDDJMarshal al 
gestore di marshaling free threaded (memorizzato come FMarshaler sopra). 

II gestore di marshaling free threaded viola le normali regole del marshaling COM 
per fornire una maggiore efficienza. Lo si deve utilizzare con cautela. In particolare, 
essa va aggregato solo con oggetti free threaded in server in-process, e va istanziato 
solo dall'oggetto che lo utilizza (non da un altro thread). 

Scrittura di un oggetto che supporta il modello apartment threading 

Per implementare il modello di threading apartment (single-threaded), occorre 
seguire poche regole: 

• II primo thread dell'applicazione che viene creato e il thread COM principale. 
Questo e generalmente il thread in cui viene chiamato WinMain. Esso deve anche 
essere l'ultimo thread che cessa di inizializzare COM. 

• Ogni thread nel modello di threading apartment deve avere un ciclo di messaggi e 
la coda dei messaggi deve essere controllata frequentemente. 

• Quando un thread fornisce un puntatore ad un'interfaccia COM, quel puntatore 
puo essere usato solo da quel thread. 

II modello single-threaded apartment e il livello intermedio tra il supporto completo 
multithreading del modello free e l'assenza del supporto del thread. Un server che si 
affida al modello apartment garantisce che il server avra un accesso serializzato a 
tutti i propri dati globali (come il proprio contatore di oggetti). Un server che si affida 
al modello apartment garantisce di avere l'accesso serializzato a tutti i suoi dati 
globali (come il suo numero di oggetti), in quanto oggetti diversi possono tentare di 
accedere ai dati globali da thread diversi. Tuttavia, i dati dell'istanza dell'oggetto 
sono al sicuro, in quanto i metodi vengono sempre chiamati sullo stesso thread. 

Generalmente, i controlli utilizzati nei browser per Web usano il modello di 
threading apartment, in quanto le applicazioni browser inizializzano sempre i loro 
thread come apartment. 

Scrittura di un oggetto che supporta il modello di threading neutral 

Sotto COM+, e possibile utilizzare un altro modello di threading che sta a meta 
strada tra il threading free e il threading apartment: il modello neutral. Come il 
modello di threading free, questo consente che molteplici thread accedano 
contemporaneamente all'oggetto. Non c'e alcun marshaling aggiuntivo per il 
trasferimento al thread in cui e stato creato l'oggetto. Tuttavia, viene garantito che 
l'oggetto non riceva chiamate in conflitto. 
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Specifica di opzioni ATL 



La scrittura di un oggetto che utilizza il modello di threading neutrale segue le stesse 
regole della scrittura di un oggetto a thread apartment, tranne che e necessario 
difendere i dati di istanza da conflitti di thread se essi possono essere richiamati da 
metodi differenti nell'interfaccia dell'oggetto. Qualsiasi dato di istanza a cui accede 
solo un singolo metodo di interfaccia e protetto automaticamente. 

Specifica di opzioni ATL 



Dopo avere utilizzato un wizard per creare un oggetto COM, la finestra di dialogo 
Project Options mette a disposizione una pagina aggiuntiva etichettata "ATL". 
Questa pagina consente di impostare un numero di flag a livello di applicazione che 
controllano quali parametri vengono generati per chiamate ATL che inizializzano 
COM o registrano l'applicazione, oltre a flag che controllano se viene attivata la 
traccia di debug nel codice che utilizza ATL. 

Utilizzare la pagina ATL per impostare le seguenti opzioni: 

• Instancing: se l'applicazione non e un server in-process, l'installazione determina 
in che modo possono essere creare molte istanze degli oggetti client all'interno di 
un singolo spazio di processo. Se si specifica l'uso singolo, allora dopo che un 
client ha istanziato l'oggetto, COM rimuove l'applicazione dalla vista in modo che 
altri client possano eseguire le proprie istanze dell'applicazione. Se si specifica 
l'uso multiplo, allora piu client possono creare ciascuno la propria istanza 
dell'oggetto, e tutte le istanze vengono eseguite nello spesso spazio di processo. 

• OLE Initialization COINIT_XXX flag: questo flag determina in che modo COM 
viene inizializzato dall'applicazione. E possibile specificare il modello di 
threading apartment, nel qual caso ciascun oggetto viene sempre chiamato nel 
thread in cui e stato creato, o multi-thread, nel qual caso gli oggetti possono essere 
chiamati in molteplici thread. I flag COINIT determinano quali modelli di 
threading possono essere utilizzati dagli oggetti nell'applicazione. Se il flag 
COINIT e impostato su apartment-threaded, nell'applicazione e possibile avere 
solo oggetti a thread singolo o apartment. L'impostazione predefinita per oggetti 
registrati con qualsiasi altro modello di threading e apartment-threaded. 

• Debugging flags: You can e anche possibile impostare flag per specificare che le 
chiamate ATL vengono registrate nel registro degli eventi quando l'applicazione 
viene eseguita nell'IDE. E possibile tracciare le chiamate ai metodi IUnknown 
(chiamate Querylnterface e conteggio dei riferimenti) o tutte le chiamate ATL. 

Definizione dell'interfaccia di un oggetto COM 



Quando si utilizza un wizard per creare un oggetto COM, la procedura genera 
automaticamente una libreria di tipi. La libreria di tipi fornisce alle applicazioni host 
un modo per scoprire cio che l'oggetto puo fare. Essa consente anche di definire 
l'interfaccia dell'oggetto tramite il Type Library editor. Le interfacce che si 
specificano nel Type Library editor definiscono quali proprieta, metodi ed eventi 
l'oggetto mette a disposizione dei client. 
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Definizione dell'interfaccia di un oggetto COM 



Se si seleziona un'interfaccia esistente nel wizard COM object, non e necessario 
aggiungere proprieta e metodi. La definizione dell'interfaccia viene importata dalla 
libreria di tipi in cui e stata definita. Invece, e sufficiente localizzare i metodi 
dell'interfaccia importata nella unit di implementazione e compilare il relativo corpo. 

Aggiunta di una proprieta all'interfaccia dell'oggetto 



Quando si aggiunge una proprieta all'interfaccia dell'oggetto tramite il Type Libary 
editor, viene aggiunto automaticamente un metodo per leggere il valore della 
proprieta e/o un metodo per impostare il valore della proprieta. II Type Library 
editor, a sua volta, aggiunge questi metodi alia classe di implementazione, e nella 
unit di implementazione crea implementazioni di metodo vuote da completare. 

Per aggiungere una proprieta all'interfaccia dell'oggetto: 

1 Nell'editor della libreria dei tipi, selezionare l'interfaccia duale per l'oggetto. 

L'interfaccia predefinita dovrebbe avere lo stesso nome dell'oggetto, con 
anteposta la lettera "I". Per determinare l'interfaccia predefinita, nel Type Library 
editor scegliere il separatore CoClass and Implements e controllare nell'elenco 
delle interfacce implementate quella contrassegnata con "Default." 

2 Per esporre una proprieta lettura/scrittura, fare clic sul pulsante Property nella 
barra degli strumenti; diversamente, fare clic sulla freccia accanto al pulsante 
Property nella barra degli strumenti, quindi fare clic sul tipo di proprieta da 
esporre. 

3 Nel quadro Attributes, specificare il nome e il tipo di proprieta. 

4 Nel quadro Attributes, specificare il nome e il tipo di proprieta. 

Nella unit di implementazione dell'oggetto viene inserita una definizione e delle 
implementazioni di partenza per i metodi di accesso della proprieta. 

5 Nella unit di implementazione localizzare i metodi di accesso per la proprieta. I 
loro nomi hanno la forma get_NomeProprieta e NomeProprieta, e includono solo 
il codice per catturare eccezioni e restituire un HRESULT. Aggiungere codice (tra 
le istruzioni try e catch) che ottenga o imposti il valore della proprieta dell'oggetto. 
Questo codice puo chiamare semplicemente una funzione esistente all'interno 
dell'applicazione, accedere a membri dati che si aggiungono alia definizione 
dell'oggetto, o implementare la proprieta in altri modi. 

Aggiunta di un metodo all'interfaccia dell'oggetto 



Quando si aggiunge un metodo all'interfaccia dell'oggetto tramite il Type Libary 
editor, questo puo, a sua volta, aggiungere i metodi alia classe di implementazione, e 
nella unit di implementazione creare implementazione vuota da completare. 

Per esporre un metodo attraverso l'interfaccia dell'oggetto: 

1 Nel Type Library editor, selezionare l'interfaccia predefinita per l'oggetto 
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L'interfaccia predefinita dovrebbe avere lo stesso nome dell'oggetto, con 
anteposta la lettera "I". Per determinare l'interfaccia predefinita, nel Type Library 
editor scegliere il separatore CoClass and Implements e controllare nell'elenco 
delle interfacce implementate quella contrassegnata con "Default." 

2 Fare clic sul pulsante Method. 

3 Nel quadro Attributes, specificare il nome del metodo. 

4 Nel quadro Parameters, specificare il tipo restituito dal metodo e aggiungere i 
parametri appropriati. 

5 Nella barra degli strumenti, fare clic sul pulsante Refresh. 

Nella unit di implementazione dell'oggetto viene inserita una definizione e delle 
implementazioni di partenza per il metodo. 

6 Nella unit di implementazione localizzare l'implementazione del nuovo metodo 
inserito. II metodo e completamente vuoto. Compilare il corpo per svolgere 
l'operazione a cui e destinato il metodo. 

Esposizione di eventi ai client 



Un oggetto COMpuo generare due eventi: eventi tradizionali ed eventi COM+. 

• Gli eventi COM+ richiedono la creazione di un oggetto evento separato tramite il 
wizard Event object e l'aggiunta di codice per chiamare l'oggetto evento 
dall'oggetto server. Per maggiori informazioni sulla generazione di eventi COM+, 
vedere "Generazione di eventi in ambiente COM+" a pagina 44-22. 

• E possibile utilizzare il wizard per gestire la maggior parte del lavoro di 
generazione di eventi tradizionali. Questo processo e descritto di seguito. 

Affinche un oggetto generi eventi, e necessario svolgere le seguenti operazioni: 

1 Nel wizard, selezionare la casella, Generateevent support code. 

II wizard crea un oggetto che include un'interfaccia Events oltre all'interfaccia 
utente predefinita. II nome di questa interfaccia Events ha la forma 
ICoClassnameEvents. E un'interfaccia rivolta all'esterno (origine), cioe non si tratta 
di un'interfaccia che l'oggetto implementa, ma un'interfaccia che i client devono 
implementare e che viene chiamata dall'oggetto. Cio puo essere verificato 
selezionando la propria CoClass, andando alia pagina Implements, e osservando 
che la colonna Source nell'interfaccia Events indica true. La GUID per l'interfaccia 
Events viene aggiunta alia mappa Connection Points, che appare sotto la mappa 
dell'interfaccia nella dichiarazione dell'oggetto. Per maggiori informazioni sulla 
mappa Connection Points, vedere la documentazione ATL. 

Oltre all'interfaccia Events, il wizard aggiunge altre classi di base all'oggetto. 
Queste include un'implementazione dell'interfaccia IConnectionPointContainer 
(IConnectionPointContainerIm.pl) e una classe modello di base che gestisce 
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l'attivazione di eventi per tutti i client (TEventsjCoClassName). II modello per 
quest'ultima classe e disponibile nello header della unit _TLB. 

2 In Type Library editor selezionare l'interfaccia Events in uscita per l'oggetto. 
(L'interfaccia e quella il cui nome e nel formato ICoClassNameEvents) 

3 Fare clic sul pulsante Method sulla barra strumenti della Type Library. Ogni 
metodo che si aggiunge all'interfaccia Events rappresenta un gestore di evento che 
il client deve implementare. 

4 Nel quadro Attributes, specificare il nome del gestore di eventi, come MyEvent. 

5 Nella barra degli strumenti, fare clic sul pulsante Refresh. 

A questo punto l'implementazione dell'oggetto ha tutto il necessario per accettare 
sink di eventi e mantenere un elenco di interfacce da chiamare quando se ne 
verifica uno.Per chiamare queste interfacce e possibile chiamare il metodo che 
attiva un evento (implementato da TEvents_CoClassName) per generare l'evento 
sui client. Per ciascun gestore di eventi, questo metodo ha un nome nella forma 
Eire_EventHandlerName. 

6 Ogni volta che e necessario attivare l'evento in modo che i client siano informati 
della sua occorrenza, chiamare il metodo che smista l'evento a tutti i sink di eventi: 

if (EventOccurs) Fire_MyEvent; // Call method you created to fire events. 

Gestione degli eventi nell'oggetto Automation 

Per supportare eventi COM tradizionali un server deve fornire la definizione di un' 
interfaccia di origine che viene implementata da un client. Questa interfaccia di 
origine include tutti i gestori di evento che il client deve implementare per 
rispondere agli eventi del server. 

Quando un client ha implementato l'interfaccia di eventi di origine, registra il suo 
interesse a ricevere la notifica dell'evento inviando una query all'interfaccia 
IConnectionPointContainer del server. L'interfaccia IConnectionPointContainer 
restituisce l'interfaccia IConnectionPoint del server, che il client utilizza per passare al 
server un puntatore alia propria implementazione dei gestori di evento (nota come 
sink). 

II server mantiene un elenco di tutti i sink client e chiama i loro metodi quando si 
verifica un evento, come e stato descritto sopra. 
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Interfacce di Automation 



Per impostazione predefinita, il wizard Automation Object implementa l'interfaccia 
duale, il che significa che entrambi gli oggetti Automation supportano 

• II binding differito in esecuzione, che avviene tramite l'interfaccia IDispatch. 
Questa viene implementata come un'interfaccia di dispatch o dispinterface. 

• II binding anticipato in fase di compilazione, che awiene tramite una chiamata 
diretta a una delle funzioni membro presenti nella tabella virtuale delle funzioni 
dell'oggetto (VTable). Questo modo viene anche detto interfaccia custom. 

Qualsiasi interfaccia generata dal wizard COM object che non deriva da IDispatch 
supporta solo chiamate VTable. 



Interfacce duali 



Una interfaccia duale e alio stesso tempo un'interfaccia custom e una dispinterface. 
Viene implementata come un'interfaccia VTable di COM derivata da IDispatch. Per 
quei controller che possono accedere all'oggetto solo in fase di esecuzione, e 
disponibile la dispinterface. Per gli oggetti che possono avvalersi del binding in fase 
di compilazione, viene utilizzata invece la piu efficiente interfaccia VTable. 

Le interfacce duali presentano i seguenti vantaggi combinati delle interfacce VTable e 
delle dispinterface: 

• Per i controller Automation che non sono in grado di ottenere informazioni di 
tipo, la dispinterface consente di accedere all'oggetto in esecuzione. 

• Per i server in-process, tramite le interfacce VTable si ottiene il beneficio di un'alta 
velocita di accesso. 

• Per i server out-of-process, COM provvede ad eseguire il marshaling dei dati sia 
per le interfacce VTable sia per le dispinterface. COM possiede 
un'implementazione proxy /stub generica in grado di eseguire il marshaling delle 
interfacce in base alle informazioni di tipo contenute in una libreria di tipi. Per 
maggiori informazioni sul marshaling, consultare, "Marshaling dei dati", a 
pagina 41-15. 

II seguente diagramma illustra l'interfaccia IMylnterfacein un oggetto che supporta 
un'interfaccia duale di nome IMy Inter face. Le prime tre voci della VTable di 
un'interfaccia duale fanno riferimento all'interfaccia IUnknown, la quattro voci 
successive fanno riferimento all'interfaccia IDispatch e la voci rimanenti sono voci 
COM per l'accesso diretto ai membri dell'interfaccia custom. 
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Interfacce di Automation 

Figura 41.1 VTable di un'interfaccia duale 
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Interfacce di dispatch 



I controller Automation sono client che usano l'interfaccia IDispatch di COM per 
accedere agli oggetti server di COM. II controller deve per prima cosa creare 
l'oggetto, quindi richiedere all'interfaccia IUnknown dell'oggetto un puntatore alia 
propria interfaccia IDispatch. IDispatch tiene traccia internamente dei metodi e delle 
proprieta tramite un identificatore di dispatch (dispID), che e un numero di 
identificazione univoco per un membro dell'interfaccia. Attraverso IDispatch un 
controller recupera le informazioni di tipo dell'oggetto per l'interfaccia dispatch e 
quindi collega i nomi dei membri dell'interfaccia ai relativi dispID. Questi dispID 
sono disponibili in fase di esecuzione e i controller li ottengono chiamando il metodo 
GetlDsOfNames di IDispatch. 

Una volta in possesso del dispID, il controller puo chiamare il metodo Invoke, di 
IDispatch per eseguire il codice appropriato (proprieta o metodo), compattando i 
parametri per la proprieta o metodo in uno dei parametri di Invoke. Invoke ha una 
segnatura fissata in fase di compilazione che gli consente di accettare un qualsiasi 
numero di argomenti quando effettua una chiamata a un metodo dell'interfaccia. 

L'implementazione di Invoke di un oggetto Automation deve quindi decompattare i 
parametri, chiamare la proprieta o il metodo e stare pronta a gestire gli eventuali 
errori che si potrebbero verificare. Al ritorno dalla proprieta o dal metodo, l'oggetto 
passa il suo valore di ritorno al controller. 

Questo modo di agire viene detto binding differito perche il controller esegue il 
binding alia proprieta o al metodo in fase di esecuzione invece che in fase di 
compilazione. 



IUnknown 
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methods 
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methods 
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Marshaling dei dati 



C++Builder non e in grado di creare CoClass che smistano interfacce non duali. La 
ragione e che il suo supporto COM si appoggia ad ATL, il quale non supporta 
interfacce dispatch non duali. 

Quando si importa una libreria di tipi, C++Builder richiedera i dispID nel momento 
in cui genera il codice, permettendo pertanto alle classi dei wrapper generate di 
chiamare Invoke senza chiamare GetlDsOfNames. Cio puo incrementare notevolmente 
le prestazioni di esecuzione dei controller. 



Interfacce custom 



Le interfacce custom sono interfacce definite dall'utente, che consentono ai client di 
chiamare i metodi dell'interfaccia in base al loro ordine nella VTable e alia 
conoscenza dei tipi degli argomenti. La VTable elenca gli indirizzi di tutte le 
proprieta e i metodi che sono membri dell'oggetto, comprese le funzioni membro 
dell'interfaccia che essa supporta. Se l'oggetto non supporta IDispatch, gli elementi 
relativi ai membri delle interfacce custom dell'oggetto sono elencati nella VTable 
subito dopo i membri di lUnknown. 

Se l'oggetto possiede una libreria di tipi, e possibile accedere all'interfaccia custom 
mediante il layout della sua VTable, che e ottenibile utilizzando il Type Library 
editor. Se l'oggetto possiede una libreria di tipi e supporta anche IDispatch, un client 
puo anche ottenere i dispID dell'interfaccia IDispatch ed eseguire il bind 
direttamente a un offset di VTable. II programma per l'importazione delle librerie di 
tipi di C++Builder (TLIBIMP) recupera i dispID al momento dell'importazione, e 
pertanto i client che utilizzano i wrapper di dispinterface possono evitare di 
chiamare GetlDsOfNames; l'informazione e gia inclusa nel file _TLB. Tuttavia, i 
client devono sempre chiamare Invoke. 



Marshaling dei dati 



Per i server out-of-process e i server remoti, occorre tener conto di come COM esegue 
il marshaling dei dati esternamente al processo corrente. E possibile fornire il 
marshaling: 

• In modo automatico, utilizzando l'interfaccia IDispatch. 

• In modo automatico, creando una libreria di tipi con il proprio server e 
contrassegnando l'interfaccia con il flag di OLE Automation. COM sa come 
eseguire il marshaling di tutti i tipi compatibili con Automation presenti nella 
libreria di tipi e impostare automaticamente i proxy e gli stub. Per consentire il 
marshaling automatico si applicano alcune restrizioni di tipo. 

• In modo manuale implementando tutti i metodi dell'interfaccia IMarshal. Questa 
modalita viene chiamata marshaling personalizzato. 

II primo metodo (che usa IDispatch) e l'unico disponibile nei server Automation. II 
secondo metodo e automaticamente disponibile su tutti gli oggetti che sono stati 
creati con un wizard e che utilizzano una libreria di tipi. 
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Tipi compatibili con Automation 



II risultato delle funzioni e i tipi dei parametri dei metodi dichiarati nelle interfacce 
duali e dispatch e le interfacce contrassegnate come OLE Automation devono essere 
di tipo compatibile con Automation. I tipi elencati di seguito sono di tipo compatibile 
con OLE Automation: 

• I tipi validi predefiniti quali short, int, single, double, WideString. Per un elenco 
complete), consultare "Tipi consentiti" a pagina 39-12. 

• I tipi enumerativi definiti in una libreria di tipi. I tipi enumerativi compatibili con 
OLE Automation vengono memorizzati come valori a 32-bit e vengono trattati 
come valori di tipo Integer in modo da consentire il passaggio dei parametri. 

• I tipi interfaccia, definiti in una libreria di tipi, che sono innocui per OLE 
Automation, vale a dire, derivati da IDispatch e contenenti solo tipi compatibili con 
OLE Automation. 

• I tipi dispinterface definiti in una libreria di tipi. 

• Qualsiasi tipo record custom definito all'intemo della libreria di tipi. 

• Wont, IStrings, e IPicture. Gli oggetti helper devono essere istanziati in modo da 
poter mappare 

• un Wont to con un TFont 

• un IStrings con un TStrings 

• un IPicture con un TPicture 

AU'occorrenza, i wizard ActiveX control e ActiveForm, creano questi oggetti 
helper automaticamente. Per utilizzare gli oggetti helper, chiamare le routine 
globali, rispettivamente GetOleFont, GetOleStrings, e GetOlePicture. 

Restrizioni di tipo per il marshaling automatico 



Affinche un'interfaccia possa supportare il marshaling automatico (detto anche 
Automation marshaling o marshaling della libreria di tipi) deve essere soggetta alle 
seguenti limitazioni. Quando si esegue l'editing dell'oggetto con l'editor della 
libreria di tipi, l'editor applica le seguenti limitazioni: 

• I tipi devono essere compatibili per poter comunicare tra piattaforme differenti. 
Ad esempio, non e possibile usare strutture dati (se non implementando un altro 
oggetto proprieta), argomenti senza segno, stringhe AnsiStrings, e cosi via. 

• I tipi di dati String devono essere trasferiti come BSTR. PChar e AnsiString non 
possono essere smistati con sicurezza. 

• Tutti i membri di un'interfaccia duale devono passare un HRESULT come valore 
di ritorno di una funzione. 

• I membri di un'interfaccia duale che restituiscono altri valori devono specificare 
l'ultimo parametro come var o out, per indicare un parametro di output che 
restituisce il valore della funzione. 
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Un modo per superare le restrizioni di tipo dettate da Automation consiste 
neH'implementare separatamente un'interfaccia IDispatch e un'interfaccia custom. In 
questo modo e possibile usare l'intera gamma dei possibili tipi di argomento. Cio 
significa che i client COM hanno la possibility di usare l'interfaccia custom, a cui i 
controller Automation possono comunque accedere. In questo caso, tuttavia, il codice 
per effettuare il marshaling deve essere implementato manualmente. 

Marshaling personalizzato 



Di solito si usa il marshaling automatico nei server out-of -process e in quelli remoti 
poiche e molto piu semplice-COM provvede a cio in modo automatico. Tuttavia, si 
potrebbe voler implementare un marshaling personalizzato nel caso si pensi che cio 
possa incrementare le prestazioni del marshaling. Quando si implementa marshaling 
personalizzato, e necessario supportare l'interfaccia IMarshal. Per maggiori 
informazioni su questo approccio, consultare la documentazione di Microsoft. 

Registrazione di un oggetto COM 



E possibile registrare l'oggetto server come server in-process o out-of -process. Per 
informazioni sugli altri tipi di server, consultare il paragrafo"Server in-process, out- 
of-process e remoti" a pagina 38-6. 

Prima di cancellare un oggetto COM dal sistema, occorre rimuoverne la 
registrazione. 

Registrazione di un server in-process 



Per registrare un server in-process (DLL or OCX): 

• Scegliere il comando Run I Register ActiveX Server. 
Per annullare la registrazione di un server in-process: 

• Scegliere il comando Run I Unregister ActiveX Server. 

Registrazione di un server out-of-process 



Per registrare un server out-of-process: 

• Eseguire il server con l'opzione della riga di comando / regserver. 

E possibile impostare le opzioni della riga di comando tramite la finestra di 
dialogo Run I Parameters. 

E anche possibile registrare il server mandandolo in esecuzione. 
Per annullare la registrazione di un server out-of-process: 

• Eseguire il server con l'opzione della riga di comando / unregserver. 
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In alternativa, si pud usare il comando tregsvr dalla riga comandi o eseguire 
regsvr32.exe dal sistema operative 

Se il server COM deve essere utilizzato sotto COM+, e necessario installarlo come 
applicazione COM+ invece di registrarlo. L'installazione dell'oggetto in 
un'applicazione COM+ provvede a gestire automaticamente la registrazione. Per 
informazioni su come installare un oggetto in un'applicazione COM+, vedere 
"Installazione di oggetti transazionali" a pagina 44-29. 



Verifica e debug deM'applicazione 



Per eseguire la verifica e il debug dell'applicazione server COM: 

1 Se occorre, attivare l'opzione relativa alle informazioni di debug presente sulla 
pagina Compiler della finestra di dialogo richiamata con Project I Options. Inoltre, 
attivare l'opzione Integrated Debugging nella finestra di dialogo richiamata con 
Tools I Debugger Options. 

2 Per un server in-process, selezionare il comando Run I Parameters, scrivere nella 
casella Host Application il nome del controller Automation e scegliere OK. 

3 Selezionare il comando Run I Run. 

4 Impostare i breakpoint nel server Automation. 

5 Utilizzare il controller Automation per interagire con il server Automation. 

L' Automation server si fermera non appena si raggiungeranno i breakpoint. 

Inoltre, puo essere utile tracciare le chiamate che l'applicazione effettua alle 
interfacce. Esaminando il flusso delle chiamate COM, e possibile determinare se 
l'applicazione si comporta secondo le previsioni. Per indicare a C++Builder di 
aggiungere messaggi nel registro degli eventi ogni volta che vene chiamata 
un'interfaccia COM, utilizzare la pagina ATL della finestra di dialogo Project objects 
per specificare le opzioni di debugging. 

Come approccio alternative nel caso si stia scrivendo anche un Automation 
controller, e possibile eseguire il debug in un server in-process attivando il supporto 
cross-process di COM. Utilizzare la pagina General della finestra di dialogo Tools I 
Debugger Options per attivare il supporto cross-process. 
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Capitolo 



42 



Creazione di Active 



Server Page 



Se si sta utilizzando Microsoft Internet Information Server (IIS) per servire le pagine 
Web, e possibile utilizzare la tecnologia Active Server Pages (ASP) per creare 
applicazioni Web client-server dinamiche. La tecnologia Active Server Pages 
consente di scrivere uno script che viene chiamato ogni volta che il server carica la 
pagina Web. Questo script, a sua volta, pud chiamare oggetti Automation per 
ottenere informazioni che includera in una pagina HTML generata. Ad esempio, e 
possibile scrivere un server Automation in C++Builder, per creare una bitmap o per 
effettuare una connessione a un database e usare questo controllo per accedere a dati 
che vengono aggiornati ogni volta che il server carica la pagina Web. 

Sul lato client, un documento ASP si comporta come un documento HTML standard 
e puo essere visualizzato dagli utenti su qualsiasi piattaforma utilizzando un 
qualsiasi Web Browser. 

Le applicazioni ASP sono analoghe alle applicazioni che sono scritte utilizzando la 
tecnologia Web Broker di C++Builder. Per maggiori informazioni sulla tecnologia 
Web broker, consultare il Capitolo 32, "Creazione di applicazioni server per 
Internet". Tuttavia, ASP si differenzia per il modo in cui separa il progetto 
dell'interfaccia utente dall'implementazione delle regole di gestione o dalla 
complessa logica dell'applicazione. 

• II progetto UI e gestito da Active Server Page. Questo e essenzialmente un 
documento HTML, ma puo inglobare script che chiamano Active Server Objects 
per fornirgli contenuti che sono il risultato delle regole di gestione o della logica 
dell'applicazione. 

• La logica dell' applicazione e incapsulata da Active Server Objects che espone ad 
Active Server Page semplici metodi, fornendogli i contenuti necessari. 

Sebbene ASP offra il vantaggio di separare il progetto UI dalla logica 
dell'applicazione, su vasta scala le sue prestazioni risultano limitate. Per quei siti web 
che rispondono ad un vasto numero di client, si raccomanda invece un approccio 
basato sulla tecnologia Web Broker. 
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Creazione di Active Server Object 

Lo script delle Active Server Page e gli oggetti Automation che vengono incorporati 
in tin Active Server Page possono fare uso degli intrinsics di ASP (oggetti interni che 
forniscono informazioni sull'applicazione corrente, sui messaggi HTTP provenienti 
dal browser e cosi via)). 

Questo capitolo mostra come creare un Active Server Object utilizzando il wizard 
Active Server Object di C++Builder. Questo speciale controllo Automation puo 
essere chiamato quindi da una Active Server Page e rifornito di contenuti. 

Di seguito sono elencati i passi necessari per creare un oggetto Active Server Object: 

• Creare un oggetto Active Server Object per l'applicazione. 

• Definire l'interfaccia dell' Active Server Object. 

• Registrare l'Active Server Object. 

• Collaudare ed eseguire il debug dell'applicazione. 

Creazione di Active Server Object 



Un Active Server Object e un oggetto Automation che ha accesso a informazioni 
sull'intera applicazione ASP intera e messaggi HTTP utilizzati per comunicare con i 
browser. Deriva da TASPObject o da TMTSASPObject (oltre che dalle classi base ATL 
CComObjectRootEx e CComCoClass), e supporta protocolli Automation, esponendo se 
stesso affinche possa essere utilizzato da altre applicazioni (o dallo script nell' Active 
Server Page). Si crea un Active Server Object utilizzando il wizard Active Server 
Object. 

II progetto Active Server Object puo essere un eseguibile (exe) o una libreria (dll), a 
seconda delle proprie necessita. Comunque, e bene essere consapevoli degli 
inconvenienti derivanti dall'utilizzo di un server out-of -process. Questi 
inconvenienti sono trattati in "Creazione di ASP per server in-process o out-of- 
process" a pagina 42-7. 

Per visualizzare il wizard Active Server Object: 

1 Scegliere il comando File I New I Other. 

2 Selezionate la pagina identificata con ActiveX. 

3 Fare doppio clic sull'icona Active Server Object. 

Nel wizard, assegnare un nome al nuovo Active Server Object e specificare il modello 
di threading che si desidera supportare. Si dovra scrivere l'implementazione in modo 
che sia conforme al modello (ad esempio, evitando conflitti di thread). II modello di 
threading coinvolge le stesse scelte che si fanno per altri oggetti COM. Per maggiori 
informazioni, consultare "Scelta di una modello di threadingl" a pagina 41-5. 

La cosa che rende unico un Active Server Object e la sua capacita di accedere alle 
informazioni sull'applicazione ASP e sui messaggi HTTP che passano tra l'Active 
Server Page e Web browser dei client. Queste informazioni vengono ottenute 
utilizzando gli intrinsics di ASP. Nel wizard e possibile specificare come l'oggetto 
accede ad essi impostando il parametro Active Server Type: 



42-2 Guida alia programmazione 



Creazione di Active Server Object 



• Se si opera con IIS 3 o IIS 4, si utilizzera Page Level Event Methods. In base a 
questo modello, 1'oggetto implementa i metodi OnStartPage e OnEndPage che 
vengono chiamati al momento del caricamento e dello scarico dell' Active Server 
Page. Quando 1'oggetto viene caricato, ottiene automaticamente un'interfaccia 
IScriptingContext che esso utilizza per accedere agli intrinsics di ASP. Queste 
interfacce, a loro volta, sono rese accessibili come proprieta ereditate dalla classe 
base (TASPObject). 

• Se si opera con IIS5 o con una versione successiva, si utilizza il tipo Object Context. 
In base a questo modello, 1'oggetto recupera un'interfaccia IObjectContext che 
utilizzera per accedere agli intrinsics di ASP. Ancora una volta, queste interfacce 
sono rese accessibili come proprieta nella classe base ereditata 
(TMTSASPObject). Uno dei vantaggi derivanti da questo secondo approccio e che 
1'oggetto ha accesso a tutti gli altri servizi disponibile tramite IObjectContext. Per 
accedere all'interfaccia IObjectContext, utilizzare la proprieta ObjectContext 

dell' Active Server Object. Per maggiori informazioni sui servizi disponibili tramite 
IObjectContext, consultare il Capitolo 44, "Creazione di oggetti MTS o COM+". 

E possibile chiedere al wizard di generare una semplice pagina ASP che ospiti il 
nuovo Active Server Object. La pagina generata fornisce uno script ridotto (stilato in 
VBScript) che crea 1' Active Server Object in base al suo ProgID, e indica dove e 
possibile chiamarne i metodi. Questo script chiama Server.CreateObject per avviare 
l'Active Server Object. 

Sebbene lo script di test generato utilizzi VBScript, le Active Server Pages possono 
anche essere scritte utilizzando Jscript. 

All'uscita dal wizard, al progetto corrente viene aggiunta una nuova unit che 
contiene la definizione dell'Active Server Object. Inoltre, il wizard aggiunge un 
progetto di libreria di tipi e apre il Type Library editor. A questo punto e possibile 
esporre le proprieta e i metodi dell'interfaccia mediante la libreria di tipi, come 
descritto nella sezione "Definizione dell'interfaccia di un oggetto COM" a 
pagina 41-9. Durante la scrittura dell'implementazione delle proprieta e dei metodi 
dell'oggetto, e possibile sfruttare gli intrinsics di ASP (descritti di seguito) per 
ottenere informazioni sull'applicazione ASP e sui messaggi HTTP utilizzati per 
comunicare con i browser. 

Gli Active Server Object, come tutti gli altri oggetti Automation, implementano una 
interfaccia duale, che supporta sia il binding anticipato (in compilazione) tramite la 
Vtable sia il binding differito (in esecuzione) tramite l'interfaccia IDispatch. Per 
informazioni sulle interfacce duali, consultare "Interfacce duali" a pagina 41-13. 

Utilizzo degli intrinsics di ASP 



Gli intrinsics di ASP sono una serie di oggetti COM messi a disposizione da ASP agli 
oggetti che vengono eseguiti in una Active Server Page. Essi consentono all' Active 
Server Object di accedere alle informazioni relative ai messaggi che intercorrono tra 
l'applicazione e il Web browser, oltre a fornire un luogo per memorizzare le 
informazioni condivise tra Active Server Objects appartenenti alia stessa 
applicazione ASP. 
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Per semplificare l'accesso a questi oggetti, la classe base dell'Active Server Object li 
rende disponibili sotto forma di proprieta. Per una conoscenza completa di questi 
oggetti, consultare la documentazione di Microsoft. I paragraf i seguenti forniscono 
una breve panoramica. 



Application 

All'oggetto Application si accede tramite un'interfaccia IApplicationObject. Esso 
rappresenta l'intera applicazione ASP, definita come l'insieme di tutti i file .asp 
contenuti in una directory virtuale e nelle sue subdirectory. L'oggetto Application 
puo essere condiviso da piu client, e pertanto include il supporto per i blocchi che si 
dovrebbe utilizzare per prevenire conflitti di thread. 

IApplicationObject include quanto segue: 

Tabella 42.1 Membri dell'interfaccia IApplicationObject 
Proprieta, metodo o evento Significato 

Proprieta Contents Elenca tutti gli oggetti aggiunti all'applicazione utilizzando 

comandi dello script. Questa interfaccia ha due metodi, Remove e 
RemoveAll che e possibile utilizzare per cancellare uno o tutti gli 
oggetti dall'elenco. 

Elenca tutti gli oggetti aggiunti all'applicazione usando il 
marcatore <OBJECT>. 

Impedisce ad altri client di bloccare l'oggetto Application finche 
non si chiama Unlock. Tutti i client dovrebbero chiamare Lock 
prima di accedere alia memoria condivisa (come le proprieta). 

Libera tutti i blocchi impostati utilizzando il metodo Lock. 

Si verifica quando l'applicazione termina, dopo l'evento 
Session_OnEnd. Gli unici intrinscs disponibili sono Application e 
Server. II gestore di evento deve essere scritto in VBScript o JScript. 

Si verifica prima che venga creata una nuova sessione (prima di 
Session_OnStart). Gli unici intrinscs disponibili sono Application e 
Server. II gestore di evento deve essere scritto in VBScript o JScript. 



Propieta StaticObjects 
Metodo Lock 

Metodo Unlock 

Evento Application_OnEnd 



Evento 

Application_OnStart 



Request 

All'oggetto Request si accede tramite un'interfaccia IRequest. Esso fornisce 
informazioni sui il messaggio di richiesta HTTP che hanno provocato l'apertura 
dell'Active Server Page. 

IRequest include quanto segue: 



Tabella 42.2 Membri dell'interfaccia IRequest 




Proprieta ClientCertificate Indica i valori di tutti i campi nel certificato del client trasmesso col 

messaggio HTTP. 



Proprieta Cookies Indica i valori di tutti gli header Cookie nel messaggio HTTP. 

Proprieta Form Indica i valori degli elementi della scheda nel corpo HTTP. A questi 

elementi e possibile accedere in base al nome. 
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Tabella 42.2 Membri dell'interfaccia IRequest (continua) 
Propriety metodo o evento Significato 

Proprieta QueryString 



Proprieta Server Variables 
TotalBytes property 
Metodo BinaryRead 



Indica i valori di tutte le variabili nella stringa della query 
dall'header HTTP. 

Indica i valori di alcune variabili di ambiente. Queste variabili 
rappresentano le piu comuni variabili di header HTTP. 

Indica il numero di byte nel corpo della richiesta. Questo e il limite 
superiore sul numero di byte restituito dal metodo BinaryRead. 

Recupera il contenuto di un messaggio Post. Chiamare il metodo 
specificando il numero massimo di byte da leggere. II contenuto 
risultante viene restituito sotto forma di array Variant di byte. 
Dopo aver chiamato BinaryRead, non e possibile utilizzare la 
proprieta Form. 



Response 

All'oggetto Response si accede tramite un'interfaccia IResponse. Consente di 
specificare le informazioni sul messaggio di risposta HTTP restituito al browser 
client. 



IResponse include quanto segue: 

Tabella 42.3 Membri dell'interfaccia IResponse 
Proprieta, metodo o evento Significato 



Proprieta Cookies 
Buffer property 



Proprieta CacheControl 
Proprieta Charset 
Proprieta ContentType 
Proprieta Expires 

Proprieta ExpiresAbsolute 

IsClientConnected 
proprieta 

Proprieta Pics 

Proprieta Status 

Metodo AddHeader 
Metodo AppendToLog 

Metodo BinaryWrite 



Determina i valori di tutti gli header Cookie nel messaggio HTTP. 

Indica se l'output della pagina e bufferizzato. Se l'output della 
pagina viene bufferizzato, il server non trasmette una risposta al 
client finche non sono stati elaborati tutti gli script del server sulla 
pagina corrente. 

Determina se i server proxy possono mettere in cache l'output nella 
risposta. 

Aggiunge il nome del set di caratteri all'header del tipo di 
contenuti. 

Specifica il tipo di contenti HTTP del corpo del messaggio di 
risposta. 

Specifica per quanto tempo la risposta puo essere tenuta in cache 
da un browser prima che scada. 

Specifica la data e l'ora di scadenza della risposta. 

Indica se il client si e disconnesso dal server. 

Imposta il valore del campo immagine-etichetta dell'header di 
risposta. 

Indica lo stato della risposta. Questo e il valore di un header di 
stato HTTP. 

Aggiunge un header HTTP con nome e valore specificati. 

Aggiunge una stringa alia fine del file di registro di un server web 
relativo a questa richiesta. 

Scrive informazioni grezze (non interpretate) nel corpo del 
messaggio di risposta. 
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Tabella 42.3 Membri dell'interfaccia IResponse (continua) 


Propriety metodo o evento 


Significato 


Metodo Clear 
Metodo End 

Metodo Flush 
Metodo Redirect 

Metodo Write 


Cancella qualsiasi output HTML bufferizzato. 

Interrompe l'elaborazione del file .asp e restituisce il risultato 
corrente. 

Trasmette immediatamente qualsiasi output bufferizzato. 

Trasmette un messaggio di risposta di tipo redirect, reindirizzando 
il browser client su un URL diverso. 

Scrive una variabile nell'output HTTP corrente sotto forma di 
stringa. 


Session 



All'oggetto Session si accede tramite l'interfaccia ISessionObject. Consente di 
memorizzare variabili che permangono per tutta la durata dell'interazione di un 
client con l'applicazione ASP. Ovvero, queste variabili non vengono azzerate quando 
il client si sposta da una pagina all'altra all'interno dell'applicazione ASP, ma 
solamente quando il client esce completamente dall'applicazione. 

ISessionObject include quanto segue: 

Tabella 42.4 Membri dell'interfaccia ISessionObject 
Proprieta, metodo o evento Significato 



Proprieta Contents 

Propieta StaticObjects 

Proprieta CodePage 

Proprieta LCID 

Proprieta SessionID 
Proprieta TimeOut 

Metodo Abandon 
Evento Session_OnEnd 

Evento Session_OnStart 



Elenca tutti gli oggetti aggiunti alia sessione utilizzando il 
marcatore <OBJECT>. E possibile accedere a qualsiasi variabile 
nell'elenco tramite nome, oppure chiamare i metodi Remove o 
RemoveAll dell'oggetto Contents per cancellare dei valori. 

Elenca tutti gli oggetti aggiunti alia sessione con il marcatore 
<OBJECT>. 

Specifica la code page da utilizzare per la mappatura dei simboli. 
Impostazioni locale diverse possono utilizzare code page diverse. 

Specifica l'identificatore dell'impostazione locale da utilizzare per 
interpretare il contenuto della stringa. 

Indica l'identificatore di sessione per il client attuale. 

Specifica per quanto tempo, in minuti, permane la sessione senza 
che vi sia una richiesta (o un aggiornamento) da parte client fino al 
termine dell'applicazione. 

Distrugge la sessione e ne libera le risorse. 

Si verifica quando la sessione vie abbandonata o va in time-out. Gli 
unici intrinsics disponibili sono Application, Server e Session. II 
gestore di evento deve essere scritto in VBScript o JScript. 

Si verifica quando il server crea una nuova sessione (dopo 
Application_OnStart ma prima di eseguire lo script sull' Active 
Server Page). Tutti gli intrinsics sono disponibili. II gestore di 
evento deve essere scritto in VBScript o JScript. 
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Server 

All'oggetto Server si accede tramite un'interfaccia IServer. Fornisce vari strumenti di 
utilita per scrivere l'applicazione ASP. 

IServer include quanta segue: 
Tabella 42.5 Membri dell'interfaccia IServer 



Proprieta, metodo o evento 

Proprieta ScriptTimeOut 
Metodo CreateObject 
Metodo Execute 
Metodo GetLastError 

Metodo HTMLEncode 

Metodo MapPath 

Metodo Transfer 
Metodo URLEncode 



Significato 

Analogo alia proprieta TimeOut dell'oggetto Session. 

Istanzia uno specifico Active Server Object. 

Esegue lo script in uno specifico file .asp. 

Restituisce un oggetto ASPError che descrive la condizione di 
errore. 

Codifica una stringa per utilizzarla in un header HTML, 
sostituendo caratteri riservati opportune costanti simboliche. 

Mappa un determinate percorso virtuale (un percorso assoluto sul 
server corrente o un percorso relativo alia pagina corrente) in un 
percorso fisico. 

Trasmette tutte le informazioni di stato correnti a un'altra Active 
Server Page affinche le elabori. 

Applica le regole di codifica degli URL, compresi i caratteri di 
escape, a una stringa specificata. 



Creazione di ASP per server in-process o out-of- process 

E possibile utilizzare Server.CreateObject in una pagina ASP per avviare server in- 
process o out-of process, in base alle proprie necessita. Comunque, l'avvio di un 
server in process e la scelta piu comune. 

A differenza della maggior parte dei server in-process, un Active Server Object in un 
server in-process non viene eseguito nello spazio di processo del client. Viene invece 
eseguito nello spazio di processo di IIS. Cio significa che il client non deve scaricare 
l'applicazione (come fa, per esempio, quando si utilizzano oggetti ActiveX). Le DLL 
di componenti in-process sono piu rapide e sicure dei server out-of-process, 
risultando cosi piu adatte per l'uso sul lata server. 

Poiche i server out-of-process sono meno sicuri, di solito IIS viene configurato per 
non ammettere eseguibili out-of-process. In questo caso, la creazione di un server out- 
of-process per l'Active Server Object potrebbe generare un errore simile al seguente: 

Server object error ' ASP 0196' 

Cannot launch out of process component 

/path/outofprocess_exe.asp, line 11 

Inoltre, i componenti out-of-process spesso creano singoli processi server per 
ciascuna istanza dell'oggetto, risultando cosi piu lenti delle applicazioni CGI. Non 
sono scalabili altrettanto bene come i componenti DLL. 

Se le prestazione e la scalabilita sono requisiti prioritari del proprio sito, si 
raccomanda l'uso di server in-process.Comunque, i siti Intranet che hanno un traffico 
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da moderato a scarso potrebbero utilizzare un componente out-of-process senza 
influenzare in modo negativo le prestazioni globali del sito. 

Per informazioni generali sui server in-process e out-of-process, consultare, "Server 
in-process, out-of-process e remoti", a pagina 38-6. 

Registrazione di Active Server Object 

E possibile registrare un oggetto Active Server Page sia come server in-process sia 
come server out-of-process. Comunque, i server in-process sono i piu comuni. 

Uv/jw Se si desidera rimuovere dal sistema l'oggetto Active Server Page, si dovrebbe per 
prima cosa annullare la registrazione, eliminando dal file di registro di Windows gli 
elementi ad esso relativi. 

Registrazione di un server in-process 



Per registrare un server in-process (DLL or OCX): 

• Scegliere il comando Run I Register ActiveX Server. 
Per annullare la registrazione di un server in-process: 

• Scegliere il comando Run I Unregister ActiveX Server. 

Registrazione di un server out-of-process 



Per registrare un server out-of-process: 

• Eseguire il server usando l'opzione / regserver della riga comandi. (E possibile 
impostare le opzioni della riga comandi mediante la finestra di dialogo 
richiamando tramite il comando Run I Parameters) 

E anche possibile registrare il server mandandolo in esecuzione. 

Per annullare la registrazione di un server out-of-process: 

• Eseguire il server usando l'opzione / unregserver della riga comandi. 

Collaudo e debug dell'applicazione Active Server Page 



II debug di un qualsiasi server in-process, come un Active Server Object, e simile al 
debug di una DLL. Si deve scegliere un'applicazione host che carichi la DLL e quindi 
eseguire il debug come al solito. Per collaudare ed eseguire il debug di un oggetto 
Active Server Object: 

1 Se occorre, attivare l'opzione relativa alle informazioni di debug presente sulla 
pagina Compiler della finestra di dialogo richiamata con Project I Options. Inoltre, 
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attivare l'opzione Integrated Debugging nella finestra di dialogo richiamata con 
Tools I Debugger Options. 

2 Selezionare il comando Run I Parameters, scrivere il nome del server web nella 
casella Host Application e scegliere OK. 

3 Selezionare il comando Run I Run. 

4 Impostare i breakpoint nell'implementazione dell'Active Server Object. 

5 Utilizzare il browser Web per interagire con 1' Active Server Page. 
II debugger si interrompe non appena viene raggiunto un breakpoint. 
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Creazione di un controllo ActiveX 



Un controllo ActiveX e un componente software che integra ed estende le 
funzionalita di una qualsiasi applicazione host in grado di supportare i controlli 
ActiveX, come C++Builder, Delphi, Visual Basic, Internet Explorer e (dato un plug- 
in) Netscape Navigator. I controlli ActiveX implementano un particolare set di 
interfacce che consentono questa integrazione. 

C++Builder, per esempio, viene fornito con diversi controlli ActiveX, che 
comprendono diagrammi, fogli elettronici e controlli grafici. E possibile aggiungere 
questi controlli alia tavolozza componenti nell'IDE, e quindi usarli come qualsiasi 
componente VCL standard, trascinandoli sulle schede e impostandone le proprieta 
tramite l'Object Inspector. 

Un controllo ActiveX pud essere distribuito anche su Web, consentendo che possa 
essere referenziato nei documenti HTML e visualizzato con i browser Web abilitati 
per ActiveX. 

C++Builder fornisce wizard che consentono di creare due tipi di controlli: 

• Controlli ActiveX che avvolgono classi VCL. Awolgendo una classe VCL, e 
possibile convertire componenti esistenti in controlli ActiveX o crearne di nuovi, 
collaudarli localmente, e quindi convertirli in controlli ActiveX. I controlli ActiveX 
sono pensati di solito per essere incorporati in una applicazione host piu grande. 

• Active form. Le Active form consentono di utilizzare il modulo di progettazione 
delle schede per creare un controllo piu elaborato che agisce come una finestra di 
dialogo o come un'applicazione completa. Una Active form viene sviluppata in 
modo molto simile a una tipi applicazione C++Builder. Le Active form sono 
pensate di solito per la distribuzione su Web. 

Questo capitolo fornisce una panoramica su come creare un controllo ActiveX 
nell'ambiente C++Builder. Lo scopo del capitolo non e quello di fornire tutti i dettagli 
implementativi per la scrittura di un controllo ActiveX senza fare ricorso a un 
wizard. Per tali informazioni, fare riferimento alia documentazione Microsoft 
Developer's Network (MSDN) o ricercare sul sito web di Microsoft le informazioni 
relative agli ActiveX. 
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Panoramica sulla creazione di controlli ActiveX 



La creazione di controlli ActiveX con C++Builder e molto simile alia creazione dei 
controlli o delle schede. L'operazione differisce sostanzialmente dalla creazione di 
altri oggetti COM, in cui per prima cosa si definisce l'interfaccia dell'oggetto e quindi 
si completa l'implementazione. Per creare controlli ActiveX (diversi dalle Active 
form), il processo viene invertito, cominciando con l'implementazione di un controllo 
VCL e quindi generando l'interfaccia e la libreria di tipi una volta scritto il controllo. 
Quando si creano Active forms, l'interfaccia e la libreria di tipi vengono create 
contemporaneamente alia scheda, e in una fase successiva si utilizza il modulo di 
progettazione della scheda per implementare la scheda. 

II controllo ActiveX completato e composto da un controllo VCL, che fornisce 
l'implementazione sottostante, un oggetto COM che avvolge il controllo VCL e una 
libreria di tipi che elenca proprieta, metodi ed eventi dell'oggetto COM. 

Per creare un nuovo controllo ActiveX (diverso da un Active Form), seguire i passi 
seguenti: 

1 Progettare e creare il controllo VCL custom che forma la base del controllo 
ActiveX. 

2 Utilizzare il wizard ActiveX control per generare un controllo ActiveX da un 
controllo VCL creato nel punto 1. 

3 Utilizzare il wizard ActiveX property page per creare una o piu pagine di 
proprieta per il controllo (facoltativo). 

4 Associare la pagina della proprieta con il controllo ActiveX (facoltativo). 

5 Registrare il controllo. 

6 Collaudare il controllo con tutte le potenziali applicazioni di destinazione. 

7 Distribuire il controllo ActiveX sul Web. (facoltativo) 

Per creare un nuovo Active form, compiere le operazioni seguenti: 

1 Utilizzare il wizard ActiveForm per creare una Active form, che appare nell'IDE 
come una scheda vuota, e un wrapper ActiveX associato a quella scheda. 

2 Utilizzare Form Designer per aggiungere componenti alia Active form e 
implementarne il comportamento, esattamente nello stesso modo con cui si crea e 
si implementate una comune scheda utilizzando Form Designer. 

3 Seguire i passi da 3 a 7 riportati in precedenza per assegnare alia Active form una 
pagina di proprieta, registrar la e distribuirla sul Web. 

Elementi di un controllo ActiveX 



Un controllo ActiveX implica molti elementi, ognuno dei quali compie una funzione 
specifica. Gli elementi comprendono un controllo VCL, un oggetto wrapper COM 
corrispondente che esponga proprieta, metodi, eventi e una o piu librerie di tipi 
associate. 
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II controllo VCL 

L'implementazione alia base di un controllo ActiveX in C++Builder e un controllo 
della VCL. Quando si crea un controllo ActiveX, per prima cosa e necessario 
progettare o scegliere il controllo VCL da cui sara generate il controllo ActiveX. 

II controllo VCL sottostante deve essere un discendente di TWinControl, in quanta 
deve avere una finestra che possa apparentarsi con l'applicazione host. Quando si 
create una Active form, questo oggetto e un discendente di TActiveForm. 

II wizard ActiveX control elenca i discendenti TWinControl disponibili fra i quali se 
ne puo sceglierne uno da trasformare in un controllo ActiveX. Questo elenco, 
comunque non include tutti i discendenti di TWinControl. Alcuni controlli, come ad 
esempio THeader Control, sono registrati come incompatibile con ActiveX (utilizzando 
la procedura RegisterNonActiveX) e non appaiono nell'elenco. 

Wrapper ActiveX 

L'oggetto COM attuale e un oggetto wrapper ActiveX per il controllo VCL. Ha il 
nome della scheda TVCLClassXImpl, in cui TVCLClass e il nome della classe del 
controllo VCL. Pertanto, per fare un esempio, il nome del wrapper ActiveX per 
TButton sarebbe TButtonXImpl. 

La classe wrapper discende dalle classi dichiarate dalla macro VCLCONTROL_IMPL 
che fornisce il supporto per le interfacce ActiveX. II wrapper ActiveX eredita questo 
supporto che gli consente di trasmettere messaggi di Windows al controllo VCL e 
apparentare la sua finestra nell'applicazione host. 

II wrapper ActiveX espone ai client le proprieta e i metodi del controllo VCL tramite 
la sua interfaccia predefinita. II wizard implementa automaticamente la maggior 
parte delle proprieta e dei metodi della classe wrapper, delegando le chiamate ai 
metodo al controllo VCL associato. II wizard fornisce anche alia classe wrapper i 
metodi che attivano gli eventi del controllo VCL sui client e assegna questi metodi 
come gestori di evento nel controllo VCL. 

La libreria di tipi 

I wizard ActiveX control generano automaticamente una libreria di tipi che contiene 
le definizioni di tipo per la classe wrapper, la sua interfaccia predefinita e tutte le 
definizioni di tipo richieste. Queste informazioni di tipo forniscono un modo per il 
controllo per rendere noti i propri servizi alle applicazioni host. E possibile 
visualizzare e modificare queste informazioni utilizzando il Type Library editor. 
Sebbene queste informazioni siano memorizzate in un file binario di libreria di tipi 
separata (estensione .TLB), esse vengono anche compilate automaticamente nel 
controllo ActiveX DLL sotto forma di risorsa. 

Pagina di proprieta 

Se si vuole, e possibile dotare il controllo ActiveX di una pagina di proprieta. La 
pagina di proprieta consente all'utente di un'applicazione host (il client) di vedere e 
modificare le proprieta del controllo. E possibile raggruppare piu proprieta su una 
sola pagina, oppure utilizza una pagina per fornire un'interfaccia per una 
determinata proprieta simile a una finestra di dialogo. Per informazioni su come 
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creare pagine di proprieta, consultare "Creazione di una pagina di proprieta per un 
controllo ActiveX" a pagina 43-14. 

Progettazione di un controllo ActiveX 



Quando si progetta un controllo ActiveX, si inizia creando un controllo VCL custom. 
In questo modo si forma la base del controllo ActiveX. Per informazioni sulla 
creazione di controlli custom, consultare la Parte V, "Creazione di componenti 
custom". 

Quando si progetta un controllo VCL, e bene ricordare che sara incorporato in 
un'altra applicazione; questo controllo non e di per se un'applicazione. Per questo 
motivo, molto probabilmente non si utilizzeranno finestre di dialogo elaborate o altri 
importanti componenti dell'interfaccia utente. Solitamente, il fine ultimo e quello di 
creare un semplice controllo con un determinato comportamento interno e che segua 
le regole dell'applicazione principale. 

Inoltre, si dovrebbe verificare che i tipi di tutte le proprieta e i metodi che si vuole 
siano esposti ai client dall'oggetto siano compatibili con Automation, poiche 
l'interfaccia del controllo ActiveX deve supportare IDispatch. II wizard non aggiunge 
alcun metodo all'interfaccia di una classe wrapper i cui parametri non siano 
compatibili con Automation. Per un elenco di tipi compatibili con Automation, 
consultare "Tipi consentiti" a pagina 39-12. 

I wizard implementano tutte le interfacce ActiveX necessarie richieste utilizzando la 
classe wrapper COM. I wizard implementano tutte le interfacce ActiveX necessarie 
richieste utilizzando la classe wrapper COM. Inoltre rendono anche accessibili tutte 
le proprieta, i metodi e gli eventi compatibili con Automation mediante l'interfaccia 
predefinita della classe wrapper. Una volta che il wizard ha generato la classe 
wrapper COM e la relativa interfaccia, e possibile utilizzare il Type Library editor per 
modificare l'interfaccia predefinita o potenziare la classe wrapper implementando 
interfacce aggiuntive. 

Generazione di un controllo ActiveX da un controllo VCL 



Per generare un controllo ActiveX da un controllo VCL, utilizzare il wizard ActiveX 
Control. Le proprieta, i metodi e gli eventi del controllo VCL diventano la proprieta, i 
metodi e gli eventi del controllo ActiveX. 

Prima di utilizzare il wizard ActiveX control, si deve decidere quale sara controllo 
VCL che dovra fornire al controllo ActiveX generato l'implementazione di base. 

Per attivare il wizard ActiveX control: 

1 Scegliere File I New I Other per aprire la finestra di dialogo New Items. 

2 Selezionare la pagina ActiveX. 

3 Fare doppio clic sull'icona ActiveX Control. 
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Nel wizard, selezionare il nome del controllo VCL che sara sviluppato dal nuovo 
controllo ActiveX. La finestra di dialogo elenca tutti i controlli disponibili, 
discendenti da TWinControl e che non sono stati registrati come incompatibile con 
ActiveX utilizzando la procedura RegisterNonActiveX. 

Se nell'elenco a discesa non si vede il controllo desiderato, controllare se e stato 
installato nell'IDE o se la sua unit e stata aggiunta al progetto. 

Una volta selezionato un controllo VCL, il wizard genera automaticamente un nome 
per la CoClass, la unit di implementazione per il wrapper ActiveX, e il progetto della 
libreria ActiveX. (Se al momento c'e un progetto di libreria ActiveX aperto, e non 
contiene un oggetto evento COM+, viene utilizzato automaticamente il progetto 
corrente). Tutti questi elementi sono modificabili nel wizard (a meno che non vi sia 
gia un progetto di libreria ActiveX aperto, nel qual caso il nome del progetto non e 
modificabile). 

II wizard specifica sempre Apartment come modello di threading. Questo non e un 
problema se il progetto ActiveX contiene, come accade di solito, solamente un 
singolo controllo. Tuttavia, se al progetto si aggiungono altri oggetti, sara compito 
del programmatore fornire il supporto per il thread. 

II wizard consente anche di configurare varie opzioni sul controllo ActiveX: 

• Attivazione della licenza: E possibile rendere il controllo soggetto a licenza in 
modo da garantirsi che gli utenti del controllo non lo possano aprire per 
utilizzarlo in altri progetti o in esecuzione a meno che non abbiano una chiave di 
licenza. 

• Inclusione di informazioni sulla versione: E possibile includere nel controllo 
ActiveX informazioni sulla versione, come un copyright o una descrizione del file. 
Queste informazioni possono essere viste in un browser. Alcuni client host, come 
Visual Basic 4.0, richiedono le informazioni di versione pena il mancato utilizzo 
del controllo ActiveX. Specificare informazioni di versione scegliendo il comando 
Project I Options e selezionando la pagina Version Info. 

• Inclusione di una finestra About: E possibile chiedere al wizard di generare una 
scheda separata che implementi una finestra About (Informazioni su) per il 
controllo. Gli utenti dell'applicazione host possono visualizzare questa finestra 
About nell'ambiente di sviluppo. Per impostazione predefinita, la finestra About 
include il nome del controllo ActiveX, un'immagine, informazioni sul copyright e 
un pulsante OK. in un secondo tempo sara possibile modificare questa scheda 
predefinita che il wizard aggiunge al progetto. 

All'uscita dal wizard, esso genera quanta segue: 

• Un file progetto ActiveX Library, che contiene il codice necessario per avviare un 
controllo ActiveX. Normalmente non c'e alcuna necessita di modificare questo file. 

• Una libreria di tipi che definisce la CoClass del controllo, l'interfaccia che essa 
espone ai client, e tutte le definizione di tipo richieste. Per maggiori informazioni 
sulla libreria di tipi, fare riferimento al Capitolo 39, "Funzionamento delle librerie 
di tipi". 

• Una unit di implementazione di ActiveX, che definisce e implementa il controllo 
ActiveX, adattato alia sintassi ATL (Active Template Library) di Microsoft 
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utilizzando la macro VCLCONTROLJMPL. Questo controllo ActiveX e 
un'implementazione perfettamente funzionante che non richiede ulteriore lavoro. 
Comunque, se voi desidera personalizzare proprieta, metodi e eventi che il 
controllo ActiveX espone ai client e possibile modificare questa classe. 

• Una unit ATL il cui nome assume il formato ActiveXControlPro] _ATL.cpp (.h), in 
cui ActiveXControlPro] e il nome del progetto. Questa unit e composta 
principalmente da istruzioni include che rendono disponibili al progetto le classi 
modello ATL e da definizioni di classi che consentono al wrapper ActiveX 
generato di operare con un oggetto VCL. Dichiara anche la variabile globale di 
nome _Module che rappresenta la libreria ActiveX alle classi di ATL. 

• Una finestra di dialogo About e una unit nel caso sia stata scelta questa opzione. 

• Un file .LIC nel caso si sia attivato il controllo sulla licenza. 

Generazione di un controllo ActiveX basato su una scheda VCL 



A differenza di altri controlli ActiveX, le Active forms non vengono prima progettate 
e poi awolte in una classe wrapper ActiveX. II wizard ActiveForm genera invece una 
scheda vuota che sara progettata alia fine, quando il wizard attivera Form Designer. 

Quando una ActiveForm viene distribuita su Web, C++Builder crea una pagina 
HTML che contiene un riferimento all' ActiveForm e specifica la sua ubicazione sulla 
pagina. La ActiveForm puo visualizzarla ed eseguirla da un Web browser. Nel 
browser la scheda si comporta esattamente come una scheda indipendente di 
C++Builder. La scheda puo contenere qualsiasi componente VCL o controllo 
ActiveX, inclusi eventuali controlli VCL custom. 

Per avviare il wizard ActiveForm: 

1 Scegliere File I New I Other per aprire la finestra di dialogo New Items. 

2 Selezionare la pagina ActiveX. 

3 Fare doppio clic sull'icona ActiveForm. 

II wizard Active form assomiglia al wizard ActiveX control, tranne che per il fatto che 
non e possibile specificare il nome della classe VCL da awolgere. Questo perche le 
Active forms sempre sono basate su T ActiveForm. 

Come nel wizard per i controlli ActiveX, e possibile modificare i nomi predefiniti 
della CoClass, della unit di implementazione e del progetto di libreria ActiveX. 
Analogamente, il wizard consente di indicare se si desidera che la Active form sia 
soggetta a licenza, se si devono includere le informazioni di versione e se si desidera 
una finestra About. 

All'uscita dal wizard, viene generato quanto segue: 

• Un file di progetto di Libreria ActiveX contenente il codice necessario per avviare 
un controllo ActiveX. Di solito questo file non viene modificato. 

• Una libreria di tipi, che definisce la CoClass del controllo, l'interfaccia che espone 
ai client, e tutte le definizioni di tipo necessarie. Per maggiori informazioni sulla 
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libreria di tipi, fare riferimento al Capitolo 39, "Funzionamento delle librerie di 
tipi". 

• Una scheda che discende da TActiveForm. Questa scheda appare nel modulo di 
impostazione della scheda, in cui sara possibile progettare in modo visuale la 
Active form che apparira ai client. La sua implementazione apparira nella unit di 
implementazione generata. 

• La dichiarazione di un wrapper ActiveX per la scheda. Questa classe wrapper e 
definita anche nella unit di implementazione, il cui nome assume il formato 
TActiveFormXImpl, in cui TActiveFormX e il nome della classe scheda. Questo 
wrapper ActiveX e un' implementazione completamente funzionante che non 
richiede alcun lavoro aggiuntivo. Comunque, se si desiderano personalizzare le 
proprieta, i metodi e gli eventi che la Active form espone ai client, e possibile 
modificare questa classe. 

• Una unit ATL il cui nome assume il formato ActiveXControlProj _ATL.cpp (.h), in 
cui ActiveXControlProj e il nome del progetto. Questa unit e composta 
principalmente da istruzioni include che rendono disponibili al progetto le classi 
modello ATL, e da definizioni di classi che consentono al wrapper ActiveX 
generato di operare con una scheda VCL. Dichiara anche la variabile globale di 
nome _Module che rappresenta la libreria ActiveX alle classi di ATL. 

• Un scheda About nel caso sia stata richiesta. 

• Un file .LIC nel caso si sia attivato il controllo sulla licenza. 

A questo punto e possibile aggiungere controlli e progettare la scheda a proprio 
piacimento. 

Dopo aver progettato e compilato il progetto ActiveForm in una libreria ActiveX (che 
ha estensione OCX), e possibile distribuire il progetto sul server Web e C++Builder 
crea una pagina HTML di verifica con un riferimento alia ActiveForm appena creata. 

Concessione in licenza di controlli ActiveX 



La concessione in licenza di un controllo ActiveX consiste nel preparare una chiave di 
licenza in fase di progettazione e nel supportare la creazione dinamica delle licenze 
se il controllo viene creato in fase di esecuzione. 

Per preparare le licenze in fase di progettazione, il wizard ActiveX crea una chiave 
per il controllo che viene registrata in un file avente lo stesso nome del progetto e 
l'estensione .LIC. Questo file .LIC viene aggiunto al progetto. L'utente del controllo 
deve possedere una copia del file LIC per aprire il controllo nell'ambiente di 
sviluppo. Ogni controllo nel progetto, per cui e stata attivata l'opzione Make Control 
Licensed, avra nel file LIC una voce di chiave separata. 

Per supportare le licenze di esecuzione, la classe wrapper implementa due metodi, 
GetLicenseString e GetLicenseFilename. Questi metodi restituiscono rispettivamente la 
stringa di licenza del controllo e il nome del file .LIC. Quando un'applicazione host 
tenta di creare il controllo ActiveX, la fabbrica di classi del controllo chiama questi 
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metodi e paragona la stringa restituita da GetLicenseString con la stringa memorizzata 
nel file .LIC. 

Le licenze di esecuzione per Internet Explorer richiedono un ulteriore livello di 
indirezione perche gli utenti possono visualizzare il codice sorgente HTML di 
qualunque pagina Web, e perche il controllo ActiveX, prima di essere visualizzato, 
viene copiato sul computer dell'utente. Per creare licenze di esecuzione per i controlli 
utilizzati con Internet Explorer, e necessario per prima cosa generare un file package 
della licenza (file LPK) e incorporare questo file nella pagina HTML che contiene il 
controllo. II file LPK e fondamentalmente un array di CLSID di controlli ActiveX e di 
chiavi di licenza. 

Per generare il file LPK, utilizzare il programma di utilita LPK_TOOL.EXE, che e 
possibile scaricare dal sito Web di Microsoft (www.microsoft.com). 

Per incorporare il file LPK in una pagina Web, utilizzare gli oggetti HTML 
<OBJECT> e <PARAM> nel seguente modo: 

<OBJECT CLASSID="clsid: 6 9 80CB9 9 - f 7 5D-84cf -B2 54 -5 5CA5 5A6 9452 " > 

<PARAM NAME="LPKPath" VALUE= "ctrllic . lpk" > 
</OBJECT> 

II CLSID identifica l'oggetto come un package di licenze e PARAM specifica 
l'ubicazione relativa del file di package di licenze rispetto alia pagina HTML. 

Quando Internet Explorer tenta di visualizzare una pagina Web contenente il 
controllo, analizza il file .LPK, estrae la chiave di licenza e, se la licenza coincide con 
la licenza del controllo (restituita da GetLicenseString), traccia il controllo sulla 
pagina. Se nella pagina Web e incluso piu di file .LPK, Internet Explorer ignora tutti i 
file tranne il primo. 

Per maggiori informazioni, cercare "Licensing ActiveX Controls" sul sito Web di 
Microsoft. 



Personalizzazione delllnterfaccia del controllo ActiveX 



I wizard ActiveX Control e ActiveForm generano un'interfaccia predefinita per la 
classe wrapper di ActiveX. Questa interfaccia predefinita espone semplicemente le 
proprieta, i metodi e gli eventi del controllo o della scheda VCL originate, con le 
seguenti eccezioni: 

• Le proprieta associate ai dati non appaiono. Poiche i controlli ActiveX hanno un 
meccanismo diverso per rendere i controlli associati ai dati rispetto ai controlli 
VCL, i wizard non convertono le proprieta relative ai dati. Per informazioni su 
come rendere data-aware il controllo ActiveX consultare "Attivazione 
dell'associazione di dati semplici con la libreria di tipi" a pagina 43-12. 

• Qualsiasi proprieta, metodo o evento il cui tipo non sia compatibile con 
Automation non appare. Se lo si desidera, potrebbero essere aggiunti 
all'interfaccia del controllo ActiveX una volta che il wizard ha terminato le 
operazioni. 
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E possibile aggiungere, modificare e rimuovere le proprieta, i metodi e gli eventi di 
un controllo ActiveX effettuando l'editing della libreria di tipi usando il Type Library 
editor come descritto nel Capitolo 39, "Funzionamento delle librerie di tipi". 

E possibile aggiungere proprieta non pubbliche all'interfaccia del controllo ActiveX. 
Tali proprieta possono essere impostate in esecuzione e appariranno neU'ambiente di 
sviluppo, ma le modifiche ad esse apportate non saranno permanenti. Owero, se 
l'utente del controllo modifica il valore di una proprieta in fase di progettazione, le 
modifiche non saranno visibili nel controllo al momento dell'esecuzione. Questo 
perche i controlli ActiveX utilizzano il sistema di streaming della VCL invece del 
sistema di streaming di ATL. Se il sorgente e un oggetto VCL e la proprieta non e 
stata resa pubblica, e possibile rendere permanenti alcune proprieta creando un 
discendente dell'oggetto VCL e rendendo pubblica la proprieta nel discendente. 

Si potrebbe anche scegliere di non esporre tutte le proprieta, i metodi e gli eventi del 
controllo VCL alle applicazioni host. E possibile utilizzare il Type Library editor per 
rimuoverli dalle interfacce generate dal wizard. Quando si rimuovono proprieta e 
metodi da un'interfaccia utilizzando il Type Library editor, il Type Library editor 
non li rimuove dalla classe dell'implementazione corrispondente. Modificare la 
classe del wrapper ActiveX nella unit di implementazione per rimuoverli dopo aver 
modificato l'interfaccia nel Type Library editor. 

Qualsiasi modifica apportata alia libreria di tipi andra perduta se si rigenera il 
controllo ActiveX dal controllo VCL o dalla scheda originali. 

E una buona idea controllare i metodi che il wizard aggiunge alia classe del wrapper 
ActiveX. Non solo si ha l'opportunia di controllare se il wizard ha omesso qualche 
proprieta associata ai dati o metodi non compatibili con Automation, ma si ha la 
possibility di lascia di scoprire i metodi per i quali il wizard non e stato in grado di 
generare un'implementazione. Tali metodi appaiono nell'implementazione con un 
commento che indica il problema. 



Aggiunta di ulteriori proprieta, metodi ed eventi 



L'aggiunta di proprieta e metodi all'interfaccia del controllo ActiveX e analoga 
all'aggiunta di proprieta, metodi e eventi ad una qualsiasi interfaccia COM. 
L'aggiunta di eventi e analoga all'aggiunta di metodi (i gestori di evento), tranne nel 
caso che li si aggiunga all'interfaccia Events invece che all'interfaccia predefinita 
dell'oggetto. L'utilizzo del Type Library editor per aggiungere proprieta e eventi e 
descritto in "Definizione dell'interfaccia di un oggetto COM" a pagina 41-9. 

Quando si esegue un'aggiunta all'interfaccia di un controllo ActiveX, spesso si sta 
solo rendendo visibile una proprieta, un metodo o un evento nel controllo VCL 
associato. I paragrafi seguenti descrivono come compiere tale operazione. 

Aggiunta di proprieta e metodi 

La classe del wrapper ActiveX implementa le proprieta nella propria interfaccia 
utilizzando metodi di accesso per la lettura e la scrittura. Owero, la classe del 
wrapper ha proprieta COM che appaiono in un'interfaccia come metodi getter e/o 
setter. A differenza delle proprieta VCL, nell'interfaccia delle proprieta COM non si 
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vedono dichiarazioni di "proprieta". Piuttosto, si vedono metodi che sono indicati 
come metodi di accesso alle proprieta. Quando si aggiunge una proprieta 
all'interfaccia predefinita del controllo ActiveX, nella definizione della classe del 
wrapper (che appare nella unit _TLB, aggiornata dal Type Library editor) vengono 
aggiunti uno o due nuovi metodi (un setter e/oun getter) che occorre implementare, 
esattamente come quando, aggiungendo un metodo all'interfaccia, alia classe del 
wrapper viene aggiunto automaticamente un metodo corrispondente da 
implementare. Pertanto, l'aggiunta di proprieta all'interfaccia della classe del 
wrapper e praticamente analoga all'aggiunta di metodi: alia definizione della classe 
del wrapper vengono aggiunte automaticamente nuove implementazioni 
scheletriche di metodo che occorre completare. 

Per maggiori informazioni su cio che appare nella unit _TLB generata, consultare 
"Codice generato durante l'importazione delle informazioni di una libreria di tipi" a 
pagina 40-5. 

Per esempio, si consideri una proprieta Caption, di tipo AnsiString nell'oggetto VCL 
associato. Quando si aggiungete questa proprieta nel Type Library editor, 
C++Builder aggiunge alia classe del wrapper le seguenti dichiarazioni: 

STDMETHOD (get_Caption (BSTR* Value) ) ; 
STDMETHOD (set_Caption (BSTR Value) ) ; 

Inoltre, aggiunge automaticamente implementazioni scheletriche di metodo da 
completare: 

STDMETHODIMP TButtonXImpl : :get_Caption (BSTR* Value) 
{ 

try 

{ 
} 

catch (Exception &e) 
{ 

return Error (e. Message. c_str () , IIDJButtonX) ; 

} 

return S_0K; 

}; 

STDMETHODIMP TButtonXImpl :: set_Caption (BSTR Value) 
{ 

try 

{ 
} 

catch (Exception &e) 
{ 

return Error (e. Message. c_str () , HD_IButtonX) ; 

} 

return S_0K; 

}; 

Di solito, e possibile implementare questi metodi semplicemente delegandoli al 
controllo VCL associato, a cui si pud accedere utilizzando il membro m_VclCtl della 
classe del wrapper: 

STDMETHODIMP TButtonXImpl :: get_Caption (BSTR* Value) 
{ 
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try 

{ 

*Value = WideString(m_VclCtl->Caption) .CopyO ; 

} 

catch (Exception &e) 
{ 

return Error (e. Message. c_str () , IID.IButtonX) ; 

} 

return S_0K; 

}; 

STDMETHODIMP TButtonXImpl : : set_Caption (BSTR Value) 
{ 

try 

{ 

m_VclCtl->Caption = AnsiString (Value) ; 

} 

catch (Exception &e) 
{ 

return Error (e. Message. c_str () , IIDJButtonX) ; 

} 

return S_0K; 

}; 

In alcuni casi, potrebbe essere necessario aggiungere del codice per convertire i tipi di 
dati COM in tipi C++ nativi. L'esempio precedente gestisce questa conversione di 
tipo. 

Aggiunta di eventi 

II controllo ActiveX puo scatenare eventi nel suo contenitore nello stesso modo in cui 
un oggetto Automation scatena eventi nei client. Questo meccanismo e descritto in 
"Esposizione di eventi ai client" a pagina 41-11. 

Se il controllo VCL utilizzato come base del controllo ActiveX non ha alcun evento 
pubblicato, i wizard aggiungono automaticamente il supporto necessario per gestire 
un elenco di eventi del client da convogliare alia classe del wrapper ActiveX e 
definiscono la dispinterface uscente che i client devono implementare per rispondere 
agli eventi. 

Per scatenare eventi sul contenitore, la classe del wrapper ActiveX deve 
implementare un gestore di evento per l'evento sull'oggetto VCL. Questo gestore di 
evento chiama il metodo Fire_EventName, implementato dalla classe 
TEvents_CoClassName definita nella unit _TLB: 

void fastcall TButtonXImpl: :KeyPressEvent (TObject *Sender, char &Key) 

{ 

short TempKey; 

TempKey = (short) Key; 
Fire_OnKeyPress (STempKey) ; 
Key = (short (TempKey; 

}; 

Si dovra in seguito assegnare questo gestore di evento al controllo VCL in modo che 
venga chiamato al verificarsi dell'evento. Per fare cio, aggiungere l'evento al metodo 
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InitializeControl che appare nella dichiarazione della classe del wrapper (nella header 
della unit di implementazione): 

void InitializeControl ( ) 
{ 

m_VclCtl->OnClick = ClickEvent; 
m_VclCtl->OnKeyPress = KeyPressEvent; 

} 

Attivazione deH'associazione di dati semplici con la libreria di tipi 



Con un semplice bind di dati e possibile associare una proprieta del controllo 
ActiveX ad un determinate) campo di un database. Per fare cio, il controllo ActiveX 
deve comunicare all'applicazione host quale valore rappresenta i dati del campo e 
quando vengono modificati. Questa comunicazione si stabilisce impostando i flag di 
binding della proprieta con il Type Library editor. 

Se si contrassegna una proprieta come bindable, quando un utente modifica la 
proprieta (quale un campo di un database), il controllo notifica al contenitore 
(l'applicazione host client) che il valore e stato modificato e richiede che il record del 
database venga aggiornato. II contenitore interagisce col database e notifica quindi al 
controllo se l'aggiornamento del record e andato a buon fine o meno. 

L'applicazione contenitore che ospita il controllo ActiveX e responsabile della 
connessione delle proprieta associate ai dati che sono state abilitate nella libreria di 
tipi per il database. Per informazioni su come scrivere un contenitore utilizzando 
C++Builder, consultare "Uso di controlli ActiveX associati ai dati" a pagina 40-9. 

Per attivare l'associazione di dati semplici utilizzare la libreria di tipi: 

1 Sulla barra strumenti, fare clic sulla proprieta che si desidera associare. 

2 Scegliere la pagina Flags. 

3 Scegliere i seguenti attributi di bind: 

Attributo Descrizione 

Bindable Indica che la proprieta supporta l'associazione di dati. Se 

l'attributo bindable e selezionato, quando il valore della proprieta 
viene modificato, la proprieta lo notifica al proprio contenitore. 

Request Edit Indica che la proprieta supporta la notifica di OnRequestEdit. 

Questo consente al controllo di chiedere al contenitore se il valore 
puo essere modificato dall'utente. 

Display Bindable Indica che il contenitore puo mostrare agli utenti che la proprieta e 

bindable. 
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P e r s o n a I i z z a z i o n e dell'interfaccia del controllo ActiveX 
Attribute Descrizione 

Default Bindable Indica la singola proprieta bindable che meglio rappresenta 

l'oggetto. Le proprieta che hanno l'attributo default bindable 
devono avere anche l'attributo bindable. Non e possibile 
specificare l'attributo su piii di una proprieta di una dispinterface. 

Immediate Bindable Consente alle singole proprieta bindable su una scheda di 

specificare questo comportamento. Quando questo bit risulta 
impostato, tutte le modifiche verranno notificate. Affinche questo 
bit attributo abbia effetto, e necessario impostare i bit di attributo 
bindable e request edit. 



4 Fare clic sul pulsante Refresh sulla barra strumenti per aggiornare la libreria di 
tipi. 

Per poter collaudare un controllo con associazione di dati, e necessario anzitutto 
registrarlo. 

Ad esempio, per convertire un controllo TEdit in un controllo ActiveX associato ai 
dati, si deve creare il controllo ActiveX a partire da TEdit e quindi cambiare i flag 
della proprieta Text in Bindable, Display Bindable, Default Bindable e Immediate 
Bindable. 

Per abilitare la modifica dei dati nel wrapper ActiveX, prima di consentire la 
modifica, il wrapper deve chiedere al proprio contenitore se e possibile modificare i 
valori. Per fare cio, non appena il controllo VCL riceve messaggi derivanti dalla 
pressione di un tasto da parte dell'utente, chiama il metodo FireOnRequestEdit, 
ereditato dalla classe base TVclComControl. II wrapper ActiveX assegna al controllo 
VCL un gestore di evento OnKeyPress. II gestore viene modificato in modo che 
assomigli a quanto segue: 

void fastcall TMyAwareEditlmpl : :KeyPressEvent (TObject *Sender, char &Key) 

{ 

signecLchar TempKey; 

const DISPID dispid = -517; // this is the dispatch id of the data-bound property 

if (FireOnRequestEdit (dispid) == S_FALSE) // ask container if edits ok? 
{ 

Key =0; // if edits not ok, cancel the keypress message 
return ; 

} 

TempKey = (signed_char)Key; 

Fire_OnKeyPress (&TernpKey) ; // this forwards the OnKeyPress event to fire in the container 
Key = (signed_char) TempKey ; 

}; 

II wrapper ActiveX deve anche notificare al contenitore se i dati hanno subito 
modifiche. Per fare cio, non appena i valori del controllo di editing vengono 
modificati, chiama il metodo FireOnChanged (ereditato da TVclComControl). 
FireOnChanged notifica al controllo che c'e qualcosa di diverse Quando i dati nel 
controllo vengono modificati, il contenitore puo mettere il dataset associato in 
modalita modifica. FireOnChanged consente anche la modifica in tempo reale dei 
campi di dati. II codice seguente mostra il gestore di evento OnChange modificato: 

void __fastcall TMyAwareEditlmpl: :ChangeEvent (TObject *Sender) 
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{ 

const DISPID dispid = -517; // the dispath id of the data-bound property 
FireOnChanged(dispid) ; // add this line to inform the container of changes 
Fire_OnChange ( ) ; // this was the original call to fire the event in the container 

}; 

Dopo aver registrato e importato il controllo, e possibile utilizzarlo per visualizzare i 
dati. 

Creazione di una pagina di proprieta per un controllo ActiveX 



Una pagina di proprieta e una finestra di dialogo simile all'Object Inspector di 
C++Builder in cui gli utenti possono cambiare le proprieta di un controllo ActiveX. 
Una pagina di proprieta consente di raggruppare piu proprieta di un controllo, in 
modo da poterle modificare alio stesso tempo. Oppure, e possibile prevedere una 
finestra di dialogo per la modifica di proprieta piu complesse. 

Normalmente, gli utenti accedono alia pagina di proprieta facendo clic con il tasto 
destro sul controllo ActiveX e scegliendo l'opzione Properties. 

II processo di creazione di una pagina di proprieta e simile a quello della creazione di 
una scheda. 

1 Creare una nuova pagina di proprieta. 

2 Aggiungere i controlli alia pagina di proprieta. 

3 Associare i controlli sulla pagina di proprieta alle proprieta di un controllo 
ActiveX. 

4 Collegare la pagina di proprieta al controllo ActiveX. 

Quando si aggiungono proprieta ad un controllo ActiveX o ad un ActiveForm, e 
necessario renderle pubbliche se si vuole che siano permanenti. Se non sono 
pubbliche nel controllo VCL associate e necessario creare un discendente custom del 
controllo VCL che dichiari di nuovo le proprieta come pubbliche, utilizzando poi il 
wizard ActiveX control per creare un controllo ActiveX dalla classe derivata. 

Creazione di una nuova pagina di proprieta 



Per creare una nuova pagina di proprieta, si utilizza il wizard Property Page. 
To create a new property page, 

1 Selezionare File I New I Other. 

2 Selezionare il separatore ActiveX. 

3 Fare doppio clic sull'icona Property Page. 

II wizard crea una nuova scheda e una nuova unit di implementazione per la pagina 
di proprieta. La scheda e un discendente di TPropertyPage il che consente di associare 
la scheda al controllo ActiveX di cui ne modifica le proprieta. Inoltre, la unit di 
implementazione dichiara un oggetto implementazione (utilizzando la macro 
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PROPERTYPAGEJMPL). Questo oggetto implementazione implementa le interfacce 
della pagina di proprieta, passando alia scheda le opportune chiamate. 

Aggiunta di controlli ad una pagina di proprieta 



Per ogni proprieta del controllo ActiveX a cui si desidera far accedere l'utente, 
occorre aggiungere un controllo alia pagina di proprieta. 

Per esempio, l'illustrazione seguente mostra una pagina di proprieta per 
l'impostazione della proprieta MaskEdit di un controllo ActiveX. 

Figura 43.1 La pagina di proprieta Mask Edit in modalita progetto 




La casella di riepilogo consente all'utente di effettuare una scelta da un elenco di 
maschere campione. I controlli di modifica consentono all'utente di verificare la 
maschera prima di applicarla al controllo ActiveX. I controlli vengono aggiunti alia 
pagina di proprieta in modo analogo all'aggiunta di controlli ad una normale scheda. 

Associazione dei controlli di una pagina di proprieta alle proprieta del 
controllo ActiveX 



Dopo aver aggiunto alia pagina di proprieta tutti i controlli necessari, occorre 
associare ogni controllo alia proprieta corrispondente. Questa associazione viene 
fatta aggiungendo del codice ai metodi UpdatePropertyPage e UpdateObject della 
pagina di proprieta. 

Aggiornamento della pagina di proprieta 

II metodo UpdatePropertyPage viene chiamato per aggiornare i controlli sulla pagina 
di proprieta quando si cambiano le proprieta del controllo ActiveX. Per aggiornare la 
pagina di proprieta con i valori correnti delle proprieta del controllo ActiveX, occorre 
aggiungere del codice al metodo UpdatePropertyPage. 

E possibile accedere al controllo ActiveX utilizzando la proprieta OleObject, che e un 
OleVariant contenente l'interfaccia del controllo ActiveX, della pagina di proprieta. 

Per esempio, il codice seguente aggiorna il controllo della pagina di proprieta 
(InputMask) con il valore corrente della proprieta EditMask del controllo ActiveX: 

void __fastcall TPropertyPagel: :UpdatePropertyPage(void) 
{ 

InputMask- >Text = OleObject .OlePropertyGet ( "EditMask" ) ; 
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} 

E anche possibile scrivere una pagina di proprieta che rappresenti piu di un controllo 
ActiveX. In questo caso, non si utilizza la proprieta OleObject. Invece, si deve scorrere 
in sequenza un elenco delle interfacce, che e conservato nella proprieta OleObjects. 

Aggiornamento dell'oggetto 

II metodo UpdateObject viene chiamato quando l'utente apporta dei cambiamenti ai 
controlli sulla pagina di proprieta. Per impostare le proprieta del controllo ActiveX ai 
loro nuovi valori, occorre aggiungere del codice al metodo UpdateObject. 

Ancora una volta si utilizzera la proprieta OleObject per accedere al controllo 
ActiveX. 

Per esempio, il codice seguente imposta la proprieta EditMask del controllo ActiveX 
usando il valore del controllo della casella di testo della pagina di proprieta 
(InputMask): 

void __fastcall TPropertyPagel: : UpdateObject (void) 
{ 

// Update OleObject from your control 

OleObject .01ePropertySet<WideString> ( "EditMask" , WideString (InputMast->Text ) .Copy ( ) ) ; 

} 

Collegamento di una pagina di proprieta ad un controllo ActiveX 



Per collegare una pagina di proprieta ad un controllo ActiveX: 

1 Nella unit di implementazione del controllo ActiveX, all'interno delle istruzione 
BEGIN_PROPERTY_MAP e END_PROPERTY_MAP, aggiungere una chiamata 
alia macro PROP_PAGE passandole il GUID della pagina di proprieta. (II GUID e 
definito nella unit di implementazione della pagina di proprieta; esso viene 
generate) automaticamente dal wizard Property Page.) 

Ad esempio, se il GUID della pagina di proprieta e definito come 
CLSID_PropertyPagel (impostazione predefinita), per un controllo ActiveX 
basato su una scheda della VCL, la sezione della mappa delle proprieta sara simile 
alia seguente: 

BEGIN_PROPERTY_MAP ( TAct lveFormXImpl ) 

// Define property pages here. Property pages are defined using 
// the PR0P_PAGE macro with the class id of the page. For example, 
/ / PR0P_PAGE ( CLSID_Act 1 veFormXPage ) 
PROP_PAGE(CLSID_PropertyPagel) 
END_PROPERTY_MAP ( ) 

2 Includere la unit della pagina di proprieta nella unit del controllo ActiveX. 

Registrazione di un controllo ActiveX 



Dopo aver creato il controllo ActiveX, occorre registrarlo in modo che le altre 
applicazioni possano trovarlo ed utilizzarlo. 
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Collaudo di un controllo ActiveX 

Per registrare un controllo ActiveX: 

• Scegliere Run I Register ActiveX Server. 

Prima di rimuovere un controllo ActiveX dal sistema, occorrera annullarne la 
registrazione. 

Per annullare la registrazione di un controllo ActiveX: 

• Scegliere Run I Unregister ActiveX Server. 

Come metodo alternative e possibile utilizzare il comando tregsvr dalla riga 
comandi oppure eseguire il programma regsvr32.exe dal sistema operativo. 

Collaudo di un controllo ActiveX 



Per verificare il controllo, aggiungerlo ad un package ed importarlo come controllo 
ActiveX. Questa procedura aggiunge il controllo ActiveX alia Component palette di 
C++Builder. E possibile trascinare il controllo su una scheda ed effettuare tutte le 
verifiche necessarie. 

II controllo dovrebbe essere verificato anche in tutte le applicazioni di destinazione 
che lo useranno. 

Per effettuare il debug del controllo ActiveX, selezionare Run I Parameters e scrivere 
il nome del client nella casella di testo Host Application. 

I parametri vengono, quindi, applicati all'applicazione host. Selezionando Run I Run 
verra eseguita l'applicazione host o client e si potranno impostare i breakpoint nel 
controllo. 

Distribuzione di un controllo ActiveX su Web 



Prima che i controlli ActiveX creati possano essere usati dai client Web, essi devono 
essere distribuiti sul server Web. Ogni volta che si apportano modifiche ad un 
controllo ActiveX, e necessario ricompilarlo e ridistribuirlo in modo che le 
applicazioni client possano vedere le modifiche. 

Prima di poter distribuire il controllo ActiveX, occorre avere un server per Web che 
risponda ai messaggi dei client. 

Per distribuire un controllo ActiveX: 

1 Selezionare Project I Web Deployment Options. 

2 Sulla pagina Project impostare Target Dir alia posizione della DLL del controllo 
ActiveX come percorso sul server Web. Questo puo essere un nome di percorso 
locale o un percorso UNC, per esempio, C:\INETPUB\wwwroot. 

3 Impostare Target URL alia posizione della DLL del controllo ActiveX, espressa 
come Uniform Resource Locators (URL) e senza indicare il nome del file, sul 
server Web, per esempio, http: / / mymachine.inprise.com/. Per maggiori 
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informazioni su come eseguire queste operazioni, consultare la documentazione 
del server Web. 

4 Impostare HTML Dir alia posizione (espressa come un percorso) in cui dovrebbe 
essere collocato il file HTML che contiene un riferimento al controllo ActiveX, per 
esempio, C:\INETPUB\wwwroot. Questo percorso puo essere un nome di 
percorso standard o un percorso UNC. 

5 Impostare le opzioni desiderate per la distribuzione su Web come descritto nella 
sezione "Impostazione delle opzioni" a pagina 43-18. 

6 Scegliere OK. 

7 Scegliere Project I Web Deploy. 

In questo modo viene creata una base per la distribuzione che contiene il controllo 
ActiveX in una libreria ActiveX (con estensione OCX). In base alle opzioni 
specificate, questa base di distribuzione puo contenere anche un file cabinet (con 
estensione CAB) o un file di informazioni (con estensione INF). 

La libreria ActiveX viene collocata nella Target Directory indicata al punto 2. II file 
HTML ha lo stesso nome del file di progetto ma con estensione HTM. Viene creato 
nella HTML Directory indicata al punto 4. II file HTML contiene un riferimento 
URL alia libreria ActiveX presente alia posizione specificata al punto 3. 

Se si desidera collocare questi file sul server Web, utilizzare un programma di 
utilita esterno come ftp. 

8 Attivare il browser Web che supporta ActiveX e visualizzare la pagina HTML 
creata. 

Quando questa pagina HTML viene visualizzata nel browser Web, la scheda o il 
controllo vengono visualizzati ed eseguiti come un'applicazione incorporata 
all'interno del browser. Vale a dire, la libreria viene eseguita nello stesso processo 
dell'applicazione browser. 

Impostazione delle opzioni 



Prima di distribuire un controllo ActiveX, occorre specificare le opzioni di 
distribuzione su Web che si dovrebbero seguire durante la creazione della libreria 
ActiveX. 

Le opzioni di distribuzione su Web consentono di impostare i seguenti parametri: 

• Including additional files: Se il controllo ActiveX dipende da altri package o da 
altri file aggiuntivi, e possibile indicare che questi dovrebbero essere distribuiti col 
progetto. Per impostazione predefinita, questi file utilizzano le stesse opzioni 
specificate per l'intero progetto, ma e possibile ridefinire queste impostazioni 
utilizzando le pagine Package o Additional files. Quando si includono package o 
file aggiuntivi, C++Builder crea un file con estensione .INF (che sta per 
INFormazioni). Questo file specifica i vari file che devono essere scaricati e 
configurati affinche sia possibile eseguire la libreria ActiveX. La sintassi del file 
INF consente di scaricare URL che puntino a package o a file aggiuntivi. 
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• CAB file compression: Un cabinet e singolo file, di solito con estensione CAB, che 
memorizza i file compressi in una libreria di file. La compressione cabinet puo 
diminuire significativamente (fino al 70%) il tempo di prelievo di un file. Durante 
l'installazione il browser espande i file memorizzati in un cabinet e li copia nel 
sistema dell'utente. Ogni file distribuito puo essere un file CAB compresso. Sulla 
pagina Project della finestra di dialogo Web Deployment options e possibile 
specificare che la libreria ActiveX utilizza file CAB compressi. 

• Version information: E possibile specificare che si desidera includere nel controllo 
ActiveX le informazioni sulla versione. Queste informazioni vengono impostate 
nella pagina Versionlnfo della finestra di dialogo Project Options. Fra queste 
informazioni c'e il numero di versione che e possibile far aggiornare 
automaticamente ogni volta che si distribuisce il controllo ActiveX. Se si includono 
package o file aggiuntivi, anche le rispettive risorse di informazioni di Versione 
potrebbero essere aggiunte al file di INF. 

A seconda del fatto che si includano file aggiuntivi e/o si utilizzino file CAB 
compressi, la libreria ActiveX risultante puo essere un file OCX, un file CAB 
contenente un file OCX, o un file INF. La tabella seguente riassume i risultati 
derivanti dalla scelta di varie combinazioni. 



Package e/o file 
aggiuntivi 


Compressione 
di file CAB 


Risultato 


No 


No 


Un file di libreria ActiveX (OCX. 


No 


Si 


Un file CAB contenente un file di libreria ActiveX. 


Si 


No 


Un file .INF, un file di libreria ActiveX ed eventuali altri file e 






package. 


Si 


Si 


Un file INF, un file CAB contenente un file di libreria 






ActiveX, e un file CAB per ciascun file o package aggiuntivo. 
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Capitolo 




Creazione di oggetti MTS o COM+ 

C++Builder utilizza il termine "oggetti transazionali" per fare riferimento a oggetti 
che sfruttano i servizi di transazione, di sicurezza e di gestione delle risorse forniti da 
Microsoft Transaction Server (MTS) (per le versioni di Windows antecedenti a 
Windows 2000) o da COM+ (per Windows 2000 e versioni successive). Questi oggetti 
sono progettati per operare in vasti ambienti distribuiti. Non possono essere 
utilizzati in applicazioni multipiattaforma a causa della loro dipendenza dalla 
tecnologia specif ica di Windows. 

C++Builder dispone di un wizard che crea oggetti transazionali cosi che possono 
sfruttare i vantaggi degli attributi COM+ o dell'ambiente MTS. Queste caratteristiche 
forniscono molti servizi accessori destinati a semplificare la creazione e 
l'implementazione di client e server COM, in particolare di server remoti. 

Per le applicazioni database, C++Builder fornisce anche un Transactional Data 
Module. Per ulteriori informazioni, consultare il Capitolo 29, "Creazione di 
applicazioni multi-tier". 

Gli oggetti transazionali utilizzano diversi servizi a basso livello, come: 

• La gestione delle risorse di sistema, compresi i processi, i thread e le connessioni al 
database in modo che l'applicazione server possa gestire molti utenti 
simultaneamente. 

• Iniziazione e controllo automatico delle transazioni in modo che l'applicazione sia 
affidabile. 

• Creazione, esecuzione e cancellazione, quando necessario, dei componenti server. 

• Fornitura di servizi di sicurezza in base al ruolo, in modo che solo gli utenti 
autorizzati possano accedere all'applicazione. 

• Gestione degli eventi in modo che i client possano rispondere alle condizioni che 
si presentano sul server (solo per COM+). 



Creazione di oggetti MTS o C0M+ 44-1 



Gli oggetti transazionali 

Lasciando a MTS o a COM+ il compito di provvedere ai servizi di base, e possibile 
concentrarsi sullo sviluppo dei particolari della specifica applicazione distribuita. La 
tecnologia scelta (MTS o COM+) dipende dal server su cui si decide di far eseguire 
l'applicazione. Dal punto di vista dei client, la differenza tra le due tecnologie (o, per 
quel che ci riguarda, il fatto che l'oggetto server utilizzi qualcuno di questi servizi) e 
trasparente (a meno che il client intervenga esplicitamente sui servizi transazionali 
mediante una speciale interfaccia). 

Gli oggetti transazionali 



Normalmente, gli oggetti transazionali sono piccoli, e vengono usati per funzioni di 
gestione discrete. Essi possono implementare le regole di gestione di 
un'applicazione, fornendo le relative viste e le trasformazioni di stato. Si consideri, 
per esempio, il caso di un'applicazione clinica di un medico. I record clinici 
memorizzati in diversi database rappresentano lo stato persistente dell'applicazione, 
come la storia clinica di un paziente. Gli oggetti transazionali aggiornano quello stato 
in modo da riflettere le modifiche quali, ad esempio, i nuovi pazienti, i risultati delle 
analisi del sangue e le radiografie. 

Gli oggetti transazionali si distinguono dagli altri oggetti COM per il fatto che 
utilizzano un set di attributi forniti da MTS o COM+ per la gestione delle 
problematiche che possono sorgere in un ambiente elaborativo distribuito. Alcuni di 
questi attributi richiedono che l'oggetto transazionale implementi l'interfaccia 
IObjectControl. IObjectControl definisce i metodi che vengono chiamati al momento 
dell'attivazione o della disattivazione dell'oggetto, in cui e possibile gestire risorse 
come le connessioni ai database. Tale interfaccia e necessaria anche per la 
condivisione degli oggetti, descritta in "Condivisione degli oggetti" a pagina 44-10. 

Se si utilizza MTS, gli oggetti transazionali devono implementare IObjectControl. In 
ambiente COM+, IObjectControl non e necessario ma se ne raccomanda l'utilizzo. II 
Transactional Object wizard fornisce un oggetto che deriva da IObjectControl. 

Un client di un oggetto transazionale e detto client base. Dal punto di vista di un 
client base, un oggetto transazionale assomiglia ad un qualsiasi altro oggetto COM. 

In ambiente MTS, 1' oggetto transazionale deve essere incluso in una libreria (DLL) 
che deve essere poi installata nell'ambiente di esecuzione di MTS (l'eseguibile di 
MTS, mtxex.exe). Ovvero, l'oggetto server viene eseguito nello spazio del processo di 
esecuzione di MTS. L'eseguibile di MTS puo essere in esecuzione nello stesso del 
client base, come processo separato sulla stessa macchina del client base o come 
processo di server remoto su una macchina separata. 

In ambiente COM+, non e necessario che l'applicazione server sia un server in- 
process. Poiche i vari servizi sono integrati nelle librerie COM, non c'e necessita che 
esista un processo MTS separato per intercettare le chiamate al server. Invece, e COM 
stesso (o meglio, COM+) a fornire la gestione delle risorse, il supporto per le 
transazioni e cosi via. Pero, l'applicazione server deve ancora essere installata questa 
volta in un'applicazione di COM+. 

La connessione tra il client base e l'oggetto transazionale e gestita da un proxy sul 
client e da un stub sul server, esattamente come con qualsiasi server out-of-process. 



44-2 Guida alia programmazione 



Gestione delle risorse 

Le informazioni della connessione sono conservate dal proxy .La connessione tra il 
client base e il proxy rimane aperta finche il client non richiede una connessione al 
server, facendo cosi sembrare che il client abbia continuamente avuto accesso al 
server. Nella realta, invece, il proxy potrebbe disattivare e riattivare l'oggetto, 
risparmiando cosi risorse in modo da consentire ad altri client di utilizzare la 
connessione. Per maggiori informazioni sull'attivazione e la disattivazione, 
consultare "Attivazione just-in-time" a pagina 44-5. 

Requisiti di un oggetto transazionale 



Oltre ai requisiti COM, un oggetto transazionale deve soddisfare i seguenti requisiti: 

• L'oggetto deve avere una fabbrica di classi standard. Questa viene preparata 
automaticamente dal wizard all'atto della creazione dell'oggetto. 

• II server deve esporre i propri oggetti classe esportando il metodo 
DUGetClassObject. II codice per questa operazione e preparato dal wizard. 

• Tutte le interfacce degli oggetti e le CoClass devono essere descritte da una libreria 
di tipi, che viene creata automaticamente dal wizard. E possibile aggiungere 
metodi e proprieta alle interfacce nella libreria di tipi usando il Type Library 
Editor. Le informazioni contenute in questa libreria sono utilizzate da MTS 
Explorer o da COM+ Component Manager per estrarre in fase di esecuzione le 
informazioni sui componenti installati. 

• II server deve esportare solo le interfacce che usano lo smistamento standard 
COM. Cio viene fatto automaticamente dal Transactional Object wizard. II 
supporto di C++Builder per gli oggetti transazionali non consente lo smistamento 
manuale delle interfacce custom. Tutte le interfacce devono essere implementate 
come interfacce duali che usano il supporto automatico dello smistamento di 
COM. 

• II server deve esportare la funzione DURegisterServer e in questa routine eseguire la 
registrazione automatica del CLSID, del ProgID, delle interfacce e della libreria di 
tipi. Tutto cio viene fornito da Transactional Object wizard. 

Se si utilizza MTS al posto di COM+, valgono anche le seguenti condizioni: 

• MTS richiede che il server sia una libreria a collegamento dinamico (DLL). I server 
implementati come file eseguibili (file .EXE) non possono essere eseguiti in 
ambiente MTS. 

• L'oggetto deve implementare l'interfaccia IObjectControl. II supporto per questa 
interfaccia viene aggiunto automaticamente dal Transactional Object wizard. 

• Un server che viene eseguito nello spazio di processo MTS non pud aggregarsi con 
oggetti COM che non sono eseguiti in MTS. 

Gestione delle risorse 



Gli oggetti transazionali possono essere amministrati per gestire meglio le risorse 
utilizzate dall'applicazione. Queste risorse includono tutto, dalla memoria per le 
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istanze degli oggetti a qualsiasi risorsa da loro utilizzata (come le connessioni ai 
database). 

In generale, l'applicazione viene configurata per come gestire le risorse in base al 
modo in cui si installa e configura l'oggetto. Si imposta l'oggetto transazionale in 
modo che possa sfruttare: 

• Attivazione just-in-time 

• Condivisione delle risorse 

• Condivisione degli oggetti (solo per COM+) 

Tuttavia, se si vuole che l'oggetto sfrutti appieno questi servizi, si deve utilizzare 
l'interfaccia IObjectContext per indicare quando e possibile rilasciare le risorse in tutta 
sicurezza. 



Accesso al contesto dell'oggetto 



Come con qualsiasi oggetto COM, prima di poter utilizzare un oggetto transazionale 
e necessario crearlo. I client COM creano un oggetto chiamando la funzione 
CoCreatelnstance della libreria COM. 

Ogni oggetto transazionale deve avere un oggetto contesto corrispondente. Questo 
oggetto contesto e implementato automaticamente da MTS o da COM+ ed e 
utilizzato per gestire l'oggetto transazionale. L'interfaccia dell'oggetto contesto e 
IObjectContext. Gli oggetti transazionali creati automaticamente dal Transactional 
Object wizard recuperano l'oggetto contesto al momento dell'attivazione. L'oggetto 
contesto viene memorizzato in una variabile membro di nome m_spObjectContext. 
Per esempio, e possibile utilizzare il puntatore all'oggetto contesto come segue: 

BOOL flags; 

m_spObjectContext->lsCallerlnRole (OLESTR ( "Manager" ) , &f lags) ; 

E possibile ottenere un puntatore all'oggetto contesto anche chiamando il metodo 
GetJDbjectContext di TMtsDll. L'oggetto TMtsDll adatta la chiamata per recuperare 
l'oggetto contesto, in modo da funzionare indipendentemente dal fatto che 
l'applicazione sia eseguita in ambiente MTS o COM+: 

IObjectContext* IAmWatchingYou = NULL; 
TMtsDll MTSDLL; 

HRESULT hr = MTSDLL. Get_ObjectContext(&IMWatchingYou) ; 

if (! ( SUCCEEDED (hr) ) ) 

{ 

// do something useful with the error 

} 

BOOL flags; 

IAmWatchingYou->IsCallerInRole(OLESTR("Manager") , if lags) ; 

Utilizzare il metodo GetJDbjectContext di TMtsDll al posto della macro 
GetObjectContext definita in comsvcs.h. Quest'ultima non e definita negli header della 
VCL per evitare la ridefinizione del metodo GetObjectContext di TDatabase. 

II membro m_spObjectContext viene assegnato utilizzando il metodo TMtsDll, che 
funziona sia in ambiente MTS sia in ambiente COM+. 
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Attivazione just-in-time 



La possibility per un oggetto di essere disattivato e riattivato mentre i client 
contengono riferimenti ad esso, viene chiamata attivazione just-in-time. Dal punto 
di vista del client, solo una singola istanza dell'oggetto esiste dal momento in cui il 
client lo crea al momento in cui lo rilascia definitivamente. In realta, e possibile che 
l'oggetto sia stato disattivato e riattivato molte volte. Avendo disattivato gli oggetti, i 
client possono contenere riferimenti all'oggetto per un tempo illimitato senza 
influenzare le risorse di sistema. Quando un oggetto viene disattivato, ne rilascia 
tutte le risorse. Per esempio, se si disattiva un oggetto, potrebbe rilasciare la sua 
connessione al database, consentendo cosi ad altri oggetti di utilizzarlo. 

Un oggetto transazionale viene creato in un stato disattivato e diviene attivo alia 
ricezione di una richiesta del client. Quando si crea un oggetto transazionale, viene 
anche creato il corrispondente oggetto contesto. Questo oggetto contesto esiste per 
tutta la durata dell'oggetto transazionale, attraverso uno o piu cicli di riattivazione. 
L'oggetto contesto, a cui si accede tramite l'interfaccia IObjectContext, tiene traccio 
dell'oggetto durante la disattivazione e coordina le transazioni. 

Gli oggetti transazionali vengono disattivati non appena e possibile farlo in tutta 
sicurezza. Questo comportamento e chiamato disattivazione as-soon-as-possible. 
Un oggetto transazionale viene disattivato quando si verifica una delle seguenti 
condizioni: 

• L'oggetto richiede la disattivazione con SetCotnplete o SetAbort: Un oggetto 
chiama il metodo IObjectContext SetComplete quando ha completato con successo il 
suo lavoro e non occorre salvare il suo stato interno per la successiva chiamata da 
parte del client. Un oggetto chiama SetAbort per indicare che non puo completare 
con successo il suo lavoro e che il suo stato non ha bisogno di essere salvato. Cioe, 
lo stato dell'oggetto ritorna alia situazione in cui si trovava prima della 
transazione corrente. Spesso gli oggetti possono essere progettati per essere senza 
stato, questo vuol dire che vengono disattivati al ritorno da ogni metodo. 

• Una transazione viene effettuata o abbandonata: Quando la transazione di un 
oggetto viene effettuata o abbandonata, l'oggetto viene disattivato. Di questi 
oggetti disattivati, gli unici che continuano ad esistere sono quelli che sono oggetto 
di riferimento da parte dei client all'esterno della transazione. Le successive 
chiamate a questi oggetti li riattivano, consentendo la loro esecuzione nella nuova 
transazione. 

• L'ultimo client rilascia l'oggetto: Naturalmente, quando un client rilascia 
l'oggetto, questo viene disattivato, ed anche il contesto dell'oggetto viene 
rilasciato. 

Se si installa l'oggetto transazionale in ambiente COM+ dall'IDE, e possibile 
specificare se l'oggetto supporta l'attivazione just-in-time utilizzando la pagina 
COM+ del Type Library editor. E sufficiente selezionare l'oggetto (CoClass) nel Type 
Library editor, andare alia pagina COM+, e selezionare o deselezionare la casella Just 
In Time Activation. Altrimenti, un amministratore di sistema deve specificare questo 
attributo utilizzando COM+ Component Manager o MTS Explorer. 
(L'amministratore di sistema puo anche ridefinire qualsiasi impostazione specifica 
utilizzando il Type Library editor.) 
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Condivisione delle risorse 



Dal momento che le risorse inattive di sistema vengono liberate durante la 
disattivazione, le risorse liberate sono disponibili per gli altri oggetti server. Per 
esempio, una connessione al database che non e piu utilizzata da un oggetto server 
puo essere riutilizzata da un altro client. Questa tecnica viene chiamata condivisione 
delle risorse. Le risorse condivise sono gestite da un distributore di risorse. 

Un distributore di risorse mette in cache le risorse, in modo che tutti gli oggetti 
transazionali installati possano condividerle. II distributore di risorse gestisce anche 
le informazioni di stato non permanenti condivise. In questo senso, i distributori di 
risorse sono simili ai manager di risorse degli SQL Server, ma senza la garanzia di 
durabilita. 

Quando si scrive un oggetto transazionale, e possibile sfruttare i due tipi di 
distributori di risorse gia forniti: 

• Distributori di risorse di database 

• Shared Property manager 

Prima che altri oggetti possano utilizzare le risorse condivise, e necessario rilasciarle 
esplicitamente. 

Distributori di risorse di database 

L'apertura e la chiusura di connessioni a un database possono utilizzare molto 
tempo. Se si utilizza un distributore di risorse per raccogliere le connessioni al 
database, l'oggetto puo riutilizzare le connessioni al database esistenti invece di 
crearne di nuove. Per esempio, se in un'applicazione di manutenzione del cliente 
sono attivi un componente per la consultazione del database e un componente per 
l'aggiornamento del database, e possibile installare insieme quei componenti, in 
modo che possano condividere le connessioni al database. In questo modo 
l'applicazione non avra bisogno di molte connessioni e le nuove istanze degli oggetto 
potranno accedere piu rapidamente ai dati utilizzando una connessione gia aperta 
ma non utilizzata. 

• Se si stanno utilizzando componenti BDE per connettersi ai dati, il distributore di 
risorse e Borland Database Engine (BDE). Questo distributore di risorse e 
disponibile solo quando l'oggetto transazionale e installato con MTS. Per attivare 
il distributore di risorse, utilizzare BDE Administrator per impostare a ON il 
parametro MTS POOLING nell'area di configurazione System/ Init. 

• Se si stano utilizzando componenti database di ADO per connettersi ai dati, il 
distributore di risorse e fornito da ADO. 

Se si stanno utilizzando componenti InterbaseExpress per l'accesso al database, non 
esiste alcun sistema precostituito per la condivisione delle risorse. 

Per i moduli dati transazionali remoti, le connessioni vengono automaticamente 
impostate in base alle transazioni di un oggetto, e il distributore di risorse puo 
ricuperare e riutilizzare automaticamente le connessioni. 
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Shared property manager 

Lo Shared Property Manager e un distributore di risorse che e possibile utilizzare per 
condividere lo stato tra piu oggetti all'intemo di un processo del server. Utilizzando 
Shared Property manager, si evita l'aggiunta all'applicazione di molto codice per 
gestire i dati condivisi: Shared Property manager li gestisce automaticamente 
implementando blocchi e semafori in modo da proteggere le proprieta condivise da 
accessi simultanei. Shared Property manager elimina le collisioni sui nomi mettendo 
a disposizione gruppi di proprieta condivise che stabiliscono spazi di nome univoci 
per le proprieta condivise in essi contenute. 

Per utilizzare la risorsa dello Shared Property manager, si deve per prima cosa usare 
la funzione helper CreateSharedPropertyGroup per creare un gruppo di proprieta 
condivise. Poi si possono scrivere tutte le proprieta in quel gruppo e leggerle da quel 
gruppo. Utilizzando un gruppo di proprieta condivise, le informazioni di stato 
vengono salvate tutte le volte che si disattiva un oggetto transazionale. Inoltre, le 
informazioni di stato possono essere condivise tra tutti gli oggetti transazionali 
installati nello stesso package MTS o nella stessa applicazione COM+. E possibile 
installare oggetti transazionali in un package secondo la modalita descritta nel 
paragrafo "Installazione di oggetti transazionali" a pagina 44-29. 

Affinche gli oggetti condividano lo stato, devono essere eseguiti tutti nello stesso 
processo. Se si desidera che istanze di componenti diversi condividano proprieta, e 
necessario installarli nello stesso package MTS o nella stessa applicazione COM+. 
Poiche c'e il rischio che gli amministratori spostino componenti da un package a un 
altro, e piu sicuro limitare l'uso di un gruppo di proprieta condivise a istanze di 
oggetti definiti nella stessa DLL o nello stesso EXE. 

Gli oggetti che condividono proprieta devono avere lo stesso attributo di attivazione. 
Se due componenti nello stesso package hanno attributi di attivazione differenti, 
normalmente non potranno condividere le proprieta. Per esempio, se un componente 
e configurato per funzionare nel processo di un client e l'altro e configurato per 
funzionare in un processo del server, i loro oggetti di solito saranno eseguiti in 
processi diversi, anche se sono inclusi nello stesso package MTS o nella stessa 
applicazione COM+. 

L'esempio seguente mostra come aggiungere del codice per supportare lo Shared 
Property manager in un oggetto transazionale: 

Esempio: Condivisione di proprieta tra istanze di un oggetto transazionale 

Questo esempio crea un gruppo di proprieta di nome MyGroup per contenere le 
proprieta da condividere tra oggetti e istanze di oggetti. In questo esempio c'e una 
proprieta Counter che viene condivisa. L'esempio utilizza la funzione helper 
CreateSharedPropertyGroup per creare il manager del gruppo di proprieta e il gruppo 
di proprieta, e poi utilizza il metodo CreateProperty dell'oggetto Group per creare una 
proprieta di nome Counter. 

Per ottenere il valore di una proprieta, si utilizza il metodo PropertyByName 
dell'oggetto Group, come mostrato di seguito. E anche possibile utilizzare il metodo 
PropertyByPos ition . 

♦include "Projectl_TLB.H" 
♦define _MTX_NOFORCE_LIBS 
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♦include <vcl\mtshlpr.h> 

class ATL_NO_VTABLE TSharedPropertyExamplelmpl : 
public CComObjectRootEx<CComSingleThreadModel>, 

public CComCoClass<TSharedPropertyExampleImpl, &CLSID_SharedPropertyExample>, 
public IObjectControl, 

public IDispatchImpl<ISharedPropertyExample, &IID_ISharedPropertyExample, &LIBID_Projectl> 

{ 

private : 

ISharedPropertyGroupManager* manager; 
ISharedPropertyGroup* PG13; 
ISharedProperty* Counter; 
public : 

TSharedPropertyExamplelmpl ( ) 
{ 

} 

DECLARE_THREADING_MODEL (ot Apartment ) ; 
DECLARE_PROGID ( " Pro j ect 1 . SharedPropertyExample " ) ; 
DECLARE_DESCRIPTION ( " " ) ; 

static HRESULT WINAPI UpdateRegistry (BOOL bRegister) 

{ 

TTypedComServerRegistrarT<TSharedPropertyExampleImpl> 
regObj (GetObjectCLSIDO , GetProglDO, GetDescriptionf) ) ; 
return regObj .UpdateRegistry (bRegister) ; 

} 

DECLARE_NOT_AGGREGAIABLE (TSharedPropertyExamplelmpl) 

BEGIN_COM_MAP (TSharedPropertyExamplelmpl) 

COM_INTERFACE_ENTRY(ISharedPropertyExample) 

COM_INTERFACE_ENTRY ( IObj ectCont rol ) 

COM_INTERFACE_ENTRY( IDispatch) 
END_COM_MAP ( ) 

public : 

STDMETHOD( Activate) () ; 
STDMETHOD(IncrementCounter() ) ; 
STDMETHOD_ ( BOOL , CanBePooled) () ; 
STDMETHOD_ (void , Deactivate)!); 

CComPtr<IObjectContext> m_spObjectContext ; 

public : 

}; 

// SHAREDPROPERTYEXAMPLEIMPL : Implementation of TSharedPropertyExamplelmpl 

♦include <vcl.h> 
♦pragma hdrstop 

♦ include 11 SHAREDPROPERTYEXAMPLEIMPL . H " 

STDMETHODIMP TSharedPropertyExamplelmpl: :Activate() 

{ 

static TMtsDll Mts; 
HRESULT hr = E_FAIL; 

hr = Mts .Get_ObjectContext (&m_spObjectContext ) ; 
if ( SUCCEEDED ( hr ) ) 
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{ 

VARIANT_B00L _false = VARIANT_FALSE ; 
VARIANT_B00L _true = VARIANT_TRUE ; 

CoCreatelnstancef CLSID_SharedPropertyGroupManager, NULL, CLSCTX_INPROC_SERVER, 

IID_ISharedPropertyGroupManager, (void** (manager) ; 
manager->CreatePropertyGroup (L"Test Group", LockSetGet, Standard, &_false, &PG13); 
if ( (PG13->CreateProperty(L n Counter", &_true, &Counter) ) == S_0K) 
{ 

Counter->put_Value(TVariant (0) ) ; 

} 

return S_OK; 

} 

return hr; 

} 

STDMETHODIMP_ (BOOL) TSharedPropertyExamplelmpl : : CanBePooled ( ) 

{ 

return FALSE; 

} 

STDMETHODIMP_ (void) TSharedPropertyExampleLmpl : : Deactivate ( ) 

{ 

PG13->Release() ; 
manager->Release() ; 
m_spObjectContext. Released ; 

} 

STDMETHODIMP TSharedPropertyExamplelmpl: : IncrementCounter ( ) 

{ 

try 

{ 

TVariant temp; 
Counter->get_Value (&temp) ; 
temp=(int)temp+l; ; 
Counter->put_Value (temp) ; 

} 

catch (Exception &e) 
{ 

return Error (e. Message. c_str () , IID_ISharedPropertyExample) ; 

} 

return S_OK; 

}; 

Rilascio delle risorse 

II programmatore si deve far carico di rilasciare le risorse di un oggetto. Di solito, 
questa operazione viene effettuata chiamando i metodi IObjectContext, SetComplete e 
SetAbort dopo aver soddisfatto le richieste di servizio dei client. Questi metodi 
rilasciano le risorse allocate dal distributore di risorse. 

Contemporaneamente occorre rilasciare i riferimenti a tutte le altre risorse, inclusi i 
riferimenti ad altri oggetti (compresi gli oggetti transazionali e gli oggetti contestuali) 
e la memoria occupata da tutte le istanze del componente (liberando il componente). 
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L'unico caso in cui non e necessario includere queste chiamate e quando si desidera 
conservare lo stato tra le chiamate del client. Per informazioni dettagliate, consultare 
"Oggetti con e senza stato" a pagina 44-13. 

Condivisione degli oggetti 



Esattamente come e possibile costituire un fondo di risorse, in ambiente COM+ e 
possibile costituire un fondo di oggetti. Al momento della disattivazione di un 
oggetto, COM+ chiama il metodo CanBePooled dell'interfaccia IObjectControl, il quale 
indica se l'oggetto pud essere condiviso per il riutilizzo. Se CanBePooled restituisce 
true, anziche essere distrutto al momento della disattivazione, l'oggetto viene 
spostato fra quelli che possono essere condivisi. Esso rimane nel fondo comune degli 
oggetti per un periodo di tempo specificato, durante il quale resta disponibile per 
l'utilizzo da parte di un qualsiasi client che ne faccia richiesta. Solo quando il fondo 
comune di oggetti e vuoto viene creata una nuova istanza dell'oggetto. Gli oggetti 
che restituiscono false o che non supportano l'interfaccia IObjectControl al momento 
della disattivazione vengono distrutti. 

La condivisione degli oggetti non e disponibile in ambiente MTS. MTS chiama 
CanBePooled come descritto, ma non ha luogo alcuna condivisione. A causa di cio, 
quando il wizard crea gli oggetti transazionali, il metodo CanBePooled generato 
restituisce sempre false. Se l'oggetto sara eseguito solamente in ambiente COM+ e si 
vuole consentire la costituzione di un fondo di oggetti, si deve individuare questo 
metodo nella unit di implementazione e modificarlo in modo che restituisca true. 

Anche se il metodo CanBePooled di un oggetto restituisce true, pud essere configurato 
in odo che COM+ non sposti nel fondo comune degli oggetti. Se si installa l'oggetto 
transazionale in ambiente COM+ dall'IDE, utilizzando la pagina COM+ del Type 
Library editor, e possibile specificare se COM+ puo tentare di includere l'oggetto nel 
fondo comune. E sufficiente selezionare l'oggetto (la CoClass) nell'editor della 
libreria di tipi, andare alia pagina COM+, e selezionare o deselezionare la casella 
Object Pooling. Altrimenti, un amministratore di sistema deve specificare questo 
attributo utilizzando COM+ Component Manager o MTS Explorer. 

Analogamente, e possibile configurare per quanto tempo un oggetto disattivato puo 
restare nel fondo comune degli oggetti prima di essere liberate Se lo si sta 
installando dall'IDE, e possibile specificare questa durata utilizzando l'impostazione 
Creation TimeOut disponibile sulla pagina COM+ dell'editor della libreria di tipi. In 
alternativa, questo attributo puo essere specificato da un amministratore di sistema 
utilizzando COM+ Component Manager o MTS Explorer. 

Supporto delle transazioni MTS e COM+ 



II supporto delle transazioni, che da il nome agli oggetti transazionali, consente di 
raggruppare azioni in transazioni. Per esempio, in un'applicazione di record clinici, 
se ci fosse un componente Transfer per trasferire i record da un medico all'altro, si 
potrebbero includere i metodi Add e Delete nella stessa transazione. In questo modo, 
o il trasferimento avverrebbe senza problemi oppure il tutto verrebbe riportato alio 
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stato precedente. Le transazioni semplificano il recupero degli errori per le 
applicazioni che devono accedere a piu database. 

Le transazioni assicurano che: 

• Tutti gli aggiornamenti di una singola transazione vengono effettuati oppure 
vengono abbandonati e riportati al loro stato precedente. Questa operazione viene 
detta atomicita. 

• Una transazione e una trasformazione corretta dello stato di un sistema, che 
preserva gli invarianti di stato. Questa operazione viene detta consistenza. 

• Le transazioni concorrenti non vedono i rispettivi risultati parziali e non 
completati, il che potrebbe creare incompatibility nello stato dell'applicazione. 
Questa operazione viene detta isolamento. I gestori delle risorse usano protocolli 
di sincronizzazione basati sulle transazioni per isolare il lavoro non completato 
delle transazioni attive. 

• Gli aggiornamenti effettuati alle risorse gestite (come i record di un database) 
soprawivono ai guasti, compresi i problemi di comunicazione, di processo e del 
sistema server. Questa operazione viene detta durability. La registrazione 
transazionale consente di recuperare lo stato durevole dopo un guasto dei 
supporti di memorizzazione su disco. 

Un oggetto contesto associato ad un oggetto indica se l'oggetto e eseguito all'interno 
di una transazione e, in tal caso, l'identita della transazione. Quando un oggetto fa 
parte di una transazione, i servizi che i manager di risorse e i distributori di risorse 
compiono per suo conto vengono eseguite anch'essi nella stessa transazione. I 
distributori di risorse utilizzano l'oggetto contesto per fornire servizi basati sulla 
transazione. Per esempio, quando un oggetto, eseguito all'intemo di una transazione, 
alloca una connessione al database utilizzando il distributore di risorse ADO o BDE, 
la connessione e assimilata automaticamente nella transazione. Tutti gli 
aggiornamenti al database che utilizzano questa connessione diventano parte della 
transazione, e vengono o confermati o annullati. 

Le operazioni derivanti da piu oggetti possono essere composti in una singola 
transazione. La possibility per un oggetto di esistere nella propria transazione o di 
essere parte di un piu vasto gruppo di oggetti, appartenenti a una singola 
transazione, e uno dei maggiori vantaggi offerti da MTS e COM+. Essa consente di 
utilizzare un oggetto in vari modi, tanto che chi sviluppa applicazioni puo 
riutilizzare il codice dell'applicazione in applicazioni diverse senza riscrivere la 
logica dell'applicazione. Infatti, gli sviluppatori possono determinare come saranno 
utilizzati gli oggetti nelle transazioni al momento deU'installazione dell'oggetto 
transazionale. Essi possono modificare il comportamento della transazione 
semplicemente aggiungendo un oggetto a un package MTS o ad un'applicazione 
COM+ differente. Per maggiori informazioni sull'installazione di oggetti 
transazionali, consultare il paragrafo "Installazione di oggetti transazionali" a 
pagina 44-29. 
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Attributi di transazione 



Ciascun oggetto transazionale ha un attributo di transazione che viene registrato nel 
catalogo MTS o memorizzato con COM+. 

C++Builder consente di impostare l'attributo di transazione in fase di progetto 
utilizzando il wizard dell'oggetto transazionale o il Type Library editor. 

Ciascun attributo di transazione puo essere impostato con questi parametri: 

Requires a Gli oggetti devono essere eseguiti all'interno del campo d'azione di 

transaction una transazione. Quando viene creato un nuovo oggetto, il suo 

contesto eredita la transazione dal contesto del client. Se il client 
non ha un contesto di transazione, ne crea automaticamente uno 
nuovo. 

Gli oggetti devono essere eseguiti all'interno delle loro transazioni. 
Quando viene creato un nuovo oggetto, una nuova transazione 
viene creata automaticamente per l'oggetto, indipendentemente 
dal fatto che il suo client abbia una transazione. Un oggetto non 
viene mai eseguito all'interno del campo d'azione della 
transazione del suo client. II sistema, invece, crea sempre 
transazioni indipendenti per i nuovi oggetti. 

Gli oggetti possono essere eseguiti all'interno del campo d'azione 
delle transazioni del loro client. Quando viene creato un nuovo 
oggetto, il suo contesto eredita la transazione dal contesto del 
client. Questo attributo rende possibile la composizione di piu 
oggetti in un'unica transazione. Se il client non ha una 
transazione, anche il nuovo contesto viene creato senza. 

Gli oggetti non vengono eseguiti nel campo d'azione delle transazioni. 
Quando si crea un nuovo oggetto, il suo contesto di oggetto viene 
creato senza una transazione, indipendentemente da fatto che il 
client abbia una transazione. Questa impostazione e disponibile 
solamente in ambiente COM+. 

Does not support II significato di questa impostazione varia, in base al fatto che si 
transactions stia installando l'oggetto in ambiente MTS o COM+. In ambiente 

MTS, questa impostazione ha lo stesso significato di Transactions 
Ignored in ambiente COM+. In ambiente COM+, non solo il 
contesto dell'oggetto viene creato senza una transazione, ma 
questa impostazione impedisce di attivare l'oggetto se il client ha 
una transazione. 

Impostazione del l'attributo di transazione 

E possibile impostare un attributo di transazione al momento della creazione di un 
oggetto transazionale utilizzando Transactional Object wizard. 

E anche possibile impostare (o modificare) l'attributo di transazione utilizzando il 
Type Library editor. Per modificare l'attributo di transazione con il Type Library 
editor: 



Requires a new 
transaction 



Supports 
transactions 



Transactions 
Ignored 
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1 Scegliere il comando View I Type Library per attivare il Type Library editor. 

2 Selezionare la classe corrispondente all'oggetto transazionale. 

3 Fare clic sulla pagina COM+ e scegliere l'attributo di transazione desiderata. 

Quando si imposta l'attributo di transazione, C++Builder inserisce uno speciale 
GUID per l'attributo specificato sotto forma di data custom nella libreria di tipi. 
Questo valore non e riconosciuto al di fuori di C++Builder. Pertanto, ha un effetto 
solamente se si installa l'oggetto transazionale dall'IDE. In alternativa, questo valore 
puo essere impostato da un amministratore di sistema utilizzando COM+ 
Component Manager o MTS Explorer. 

Quando si modifica l'attributo di transazione, se l'oggetto transazionale e gia 
installato, occorre prima disinstallarlo e successivamente reinstallarlo. Per eseguire 
queste operazioni, utilizzare i comandi Use Run I Install MTS objects o Run I Install 
COM+ objects. 



Oggetti con e senza stato 



Come qualsiasi altro oggetto COM, gli oggetti transazionali possono mantenere lo 
stato interno per diverse interazioni con un client. Per esempio, il client potrebbe 
impostare un valore di una proprieta durante una chiamata, e aspettarsi che quel 
valore di proprieta rimanga immutato alia chiamata successiva. Tale oggetto e detto 
essere con stato. Gli oggetti transazionali possono essere anche senza stato, il che 
vuol dire che non contengono stati intermedi durante l'attesa della chiamata 
successiva da parte di un client. 

Quando una transazione viene completata o abbandonata, tutti gli oggetti che sono 
coinvolti nella transazione vengono disattivati, causando la perdita di qualsiasi stato 
acquisito nel corso della transazione. Questa operazione aiuta a garantire 
l'isolamento della transazione e la coerenza del database; inoltre, libera le risorse del 
server affinche siano utilizzate in altre transazioni. II completamento di una 
transazione consente di reclamare le risorse utilizzate da un oggetto al momento 
della sua disattivazione. Per informazioni su come controllare quando viene 
rilasciato lo stato di una oggetto, consultare la sezione seguente. 

II mantenimento dello stato su un oggetto richiede che l'oggetto rimanga attivato, 
conservando risorse potenzialmente preziose come le connessione ad un database. 



Come influenzare la modalita di completamento delle transazioni 



Un oggetto transazionale utilizza i metodi di IObjectContext come mostrato nella 
tabella seguente per influenzare la modalita di completamento di una transazione. 
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Questi metodi, insieme all'attributo di transazione dell'oggetto, consentono di 
includere uno o piu oggetti in un'unica transazione. 

Tabella 44.1 Metodi lObjectContext per il supporto delle transazioni 



SetComplete Indica che l'oggetto ha completato con successo le operazioni relative alia 
transazione. L'oggetto viene disattivato al ritorno dal metodo che prima ha 
immesso il contesto. L'oggetto viene riattivato alia successiva chiamata che 
richiede l'esecuzione dell'oggetto. 

SetAbort Indica che il lavoro dell'oggetto non potra mai essere effettuato e la 

transazione dovrebbe essere ripristinata alio stato originale. L'oggetto viene 
disattivato al ritorno dal metodo che prima ha immesso il contesto. L'oggetto 
viene riattivato alia successiva chiamata che richiede l'esecuzione dell'oggetto. 

EnableCommit Indica che il lavoro dell'oggetto non e necessariamente eseguito, ma che gli 
aggiornamenti transazionali possono essere completati nella loro forma 
attuale. Utilizzare questo metodo per ritenere lo stato tra piu chiamate 
successive di un client, consentendo al contempo il completamento delle 
transazioni. L'oggetto non viene disattivato finche non chiama SetComplete o 
SetAbort. 

EnableCommit e lo stato predefinito quando un oggetto viene attivato. Questo 
si verifica perche un oggetto chiamera sempre SetComplete o SetAbort -prima di 
ritornare da un metodo, a meno che l'oggetto non mantenga il suo stato interno 
per la chiamata successiva da un client. 

DisableCommit Indica che il lavoro dell'oggetto e inconsistente e che non puo essere 

completato finche non vengono ricevute ulteriori chiamate del metodo dal 
client. Questo metodo deve essere chiamato prima di restituire il controllo al 
client per mantenere lo stato tra piu chiamate successive del client 
mantenendo attiva al contempo la transazione corrente. 

DisableCommit impedisce la disattivazione dell'oggetto ed il rilascio delle sue 
risorse al ritorno da una chiamata a un metodo. Una volta che un oggetto ha 
chiamato DisableCommit, se un client cerca di effettuare la transazione prima 
che l'oggetto abbia chiamato EnableCommit o SetComplete, la transazione 
viene abbandonata. 



Inizio di transazioni 



Le transazioni possono essere controllate in tre modi: 

• Possono essere controllate dal client. 

I client possono avere un controllo diretto sulle transazioni utilizzando un oggetto 
contesto di transazione (utilizzando l'interfaccia ITransactionContext). 

• Possono essere controllate dal server. 

I server possono controllare le transazioni creando esplicitamente per esse un 
oggetto contesto. Quando il server crea un oggetto in tal modo, l'oggetto creato 
viene assimilato automaticamente nella transazione corrente. 

• Le transazioni possono verificarsi automaticamente come risultato dell'attributo 
di transazione dell'oggetto. 
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Gli oggetti transazionali possono essere dichiarati in modo che i rispettivi oggetti 
siano sempre eseguiti all'interno di una transazione, indipendentemente da come 
gli oggetti sono stati creati. In questo modo, gli oggetti non devono includere 
alcuna logica per gestire le transazioni. Questa caratteristica riduce anche il carico 
sulle applicazioni client. I client non dovranno iniziare una transazione 
semplicemente perche il componente che stanno utilizzando lo richiede. 

Impostazione di un oggetto transazionale sul lato client 

Un'applicazione basata su client puo controllare il contesto della transazione tramite 
l'interfaccia ITransactionContextEx. L'esempio di codice che segue mostra come 
un'applicazione client utilizza CreateTransactionContextEx per creare il contesto della 
transazione. Questo metodo restituisce un'interfaccia per questo oggetto. 

♦include <vcl\mtshlpr.h> 

int main(int argc, char* argv[]) 

{ 

// first, create a transactional object, [requires C0M+ or local installation of MTS] 
TCOMITransactionClientExample first_client = CoIransactionClientExample :: Create () ; 
//then, check to see if it's in a transaction. 
ITransactionContext* TCTX; 

HRESULT happily^transacting = f irst_client->QueryInterface (IID_ITransactionContext , 
(void**)&TCTX) ; 

// if it is in a transaction, you can do your data access calls from here 
// and then call Commit or Abort yourself instead of waiting for the 
// transactional object to do so. 

if (happily_transactmg) 
{ 

TVariant database = "name"; 
TVariant record = "data"; 
TVariant flag; 

first_client .UpdateData (Scdatabase, Srecord, if lag) ; 
flag ? TCTX->Commit() : TCTX->Abort ( ) ; 

} 

else 

{ 

// otherwise, you can create a transaction: 
ITransactionContextEx* TXCTX = CreateTransactionContextEx () ; 

// and an object, any objects you create in this fashion 

// will be enlisted in the transaction represented by this object. 

TCOMITransactionClientExample* second_client ; 

TXCTX->CreateInstance (CLSID_TransactionClient Example, I ID_ITransactionClient Example, 
(void**)&second_client) ; 

// and then perform your data access and commit or abort. 

TVariant database = "name"; 
TVariant record = "data"; 
TVariant flag; 

second_client->UpdateData (&database, krecord, &f lag) ; 
flag ? TXCTX->Commit() : TXCTX->Abort ( ) ; 
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} 

return 0; 

} 

Impostazione di un oggetto transazionale sul lato server 

Per controllare il contesto della transazione sul lato server, si crea un'istanza di 
ObjectContext. Nell'esempio seguente il metodo Transfer si trova nell'oggetto 
transazionale. Usando ObjectContext in questo modo, l'istanza creata dell'oggetto 
ereditera tutti gli attributi di transazione dell'oggetto che la crea. 

♦include <vcl\mtshlpr.h> 

STDMETHODIMP TTransactionServerExamplelmpl : :DoTransactionContext (long execflag) 

{ 

if (m_spObjectContext->IsInTransaction() ) 
{ 

// this means the current object has a transaction, and can pass 
// its transaction information to its children. 
// for simplicity, this object simply creates another object of its 
// own type, within the same transaction. 

// NOTE: you are still responsible for aggregating, if appropriate; 

if (execflag) 

{ 

TCOMITransactionServerExample* inner; 

m_spObjectContext->CreateInstance (CLSID^Transact ionServerExample, 

IID_ITransactionServerExample, (void**) Sinner) ; 
mner->DoTransactionContext (false) ; 

// add data access code here. data_access_succeeded( ) below is 
// an unimplemented placeholder. 

data_access_succeeded() ? m_spObjectContext->EnableCommit ( ) 
: m_spObjectContext->DisableCommit ( ) ; 

} 

} 

else 

{ 

//this means the current object has no transaction, and must 
//create one the way a client would. 

ITransactionContextEx* TCTX = CreateTransactionContextEx ( ) ; 
TCOMITransact ionServerExample* inner ; 

// afterwards, follow the same steps. 

TCTX->CreateInstance (CLSID_Transact ionServerExample, 

IID_ITransactionServerExample, (void** ) &mner) ; 
inner->DoTransactionContext (true) ; 

// add data access code here. data_access_succeeded() below is 
// an unimplemented placeholder. 

data_access_succeeded() ? TCTX->Commit ( ) : TCTX->Abort ( ) ; 

} 

} 
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Durata della transazione 



La durata della transazione imposta per quanta tempo (in secondi) puo rimanere 
attiva una transazione. II sistema annulla automaticamente le transazioni che 
risultano ancora attive alia scadenza di tale intervallo temporale. Per impostazione 
predefinita, il valore della durata e 60 secondi. E possibile disattivare la durata delle 
transazioni specificando un valore 0, il che e utile durante il debug degli oggetti 
transazionali. 

Per impostare il valore di time-out sul computer: 

1 In MTS Explorer o in COM+ Component Manager, selezionare Computer, My 
Computer. 

Per impostazione predefinita, My Computer corrisponde al computer locale. 

2 Fare clic con il tasto destro e scegliere Properties e quindi la pagina Options. 

La pagina Options viene usata per impostare la proprieta di time-out della 
transazione del computer. 

3 Cambiare il valore di time-out in per disattivare la durata delle transazioni. 

4 Fare clic su OK per salvare l'impostazione. 

Per ulteriori informazioni sul debug di applicazioni MTS, consultare "Debug e 
collaudo di oggetti transazionali" a pagina 44-28. 

Sicurezza basata sul ruolo 



Attualmente MTS e COM+ forniscono la sicurezza basata sul ruolo, che prevede 
appunto l'assegnazione di un ruolo ad un gruppo logico di utenti. Per esempio, 
un'applicazione di informazioni mediche potrebbe definire i ruoli dei medici, dei 
radiologi e dei pazienti. 

Si deve definire l'autorizzazione per ciascun oggetto e interfaccia assegnando i ruoli. 
Per esempio, nell'applicazione per i medici, solo il medico puo essere autorizzato a 
vedere tutti i record clinici, mentre il radiologo puo vedere solo le radiografie e i 
pazienti possono vedere solo i propri record. 

Normalmente, i ruoli vengono definiti durante lo sviluppo dell'applicazione e 
vengono assegnati a ciascun package MTS o applicazione COM+. Questi ruoli 
vengono quindi assegnati agli specifici utenti quando l'applicazione viene 
distribuita. Gli amministratori possono configurare i ruoli usando MTS Explorer o 
COM+ Component Manager. 

Se si vuole controllare l'accesso per bloccare il codice invece dell'intero oggetto, e 
possibile introdurre una sicurezza ancora piu mirata utilizzando il metodo 
IsCallerlnRole di IObjectContext. Tale metodo funziona sole se la sicurezza e attivata, 
cosa che puo essere controllata chiamando il metodo IsSecurityEnabled di 
IObjectContext. Ad esempio: 

if (m_spObjectContext. IsSecurityEnabled! ) ) // check if security is enabled 
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{ 

if ( !m_spObjectContext . IsCallerlnRole ( "Physician" ) ) // check caller's role 
{ // If not a physician, do something appropriate here. 

} 

else 

{ // execute the call normally 
} 

} 

else // no security enabled 
{ // do something appropriate 
} 

Per le applicazioni che necessitano di una sicurezza piu forte, gli oggetti contesto 
implementano l'interfaccia ISecurityProperty, i cui metodi consentono il reperimento 
dell'identificatore di sicurezza di Window (SID) del chiamante diretto e del creatore 
dell'oggetto, oltre che del SID dei client che stanno utilizzando l'oggetto. 



Panoramica sulla creazione di oggetti transazionali 



II processo di creazione di un oggetto transazionale e il seguente: 

1 1 Usare Transactional Object wizard per creare un oggetto transazionale. 

2 Aggiungere i metodi e le proprieta all'interfaccia dell'oggetto usando il Type 
Library editor. Per informazioni dettagliate sull'aggiunta di metodi e proprieta 
usando il Type Library editor, consultare il Capitolo 39, "Funzionamento delle 
librerie di tipi". 

3 Durante l'implementazione dei metodi dell'oggetto e possibile utilizzare 
l'interfaccia IObjectContext per gestire le transazioni, lo stato permanente e la 
sicurezza. Inoltre, se si passano riferimenti a oggetti, e necessario porre particolare 
attenzione affinche siano gestiti in modo corretto. (Consultare "Passaggio di 
riferimenti a oggetti" on page 27.) 

4 Correggere e collaudare l'oggetto transazionale. 

5 Installare l'oggetto transazionale in un package MTS o in un'applicazione COM+. 

6 Amministrare gli oggetti usando MTS Explorer o COM+ Component Manager. 

Uso di Transactional Object wizard 



Transactional Object wizard viene utilizzato per creare oggetti COM in grado di 
sfruttare i vantaggi derivanti dalla gestione delle risorse, dall'elaborazione delle 
transazioni e dalla sicurezza basata sui ruoli, messi a disposizione da MTS o COM+. 

Per visualizzare Transactional Object wizard: 

1 Scegliere il comando File I New I Other. 

2 Selezionare la pagina ActiveX. 

3 Fare doppio clic sull'icona Transactional Object. 
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Nel wizard si deve specificare quanto segue: 

• Un modello di thread che indichi come le applicazioni client possano chiamare 
l'interfaccia dell'oggetto. II modello di thread scelto determina come viene 
registrato l'oggetto. Chi programma deve accertarsi che l'implementazione 
dell'oggetto sia coerente con il modello selezionato. Per ulteriori informazioni sui 
modelli di thread, consultare "Scelta di un modello di threading per un oggetto 
transazionale" a pagina 44-19. 

• Un modello transazionale 

• Una indicazione del fatto che l'oggetto notifichi o meno gli eventi ai client. II 
supporto degli eventi e previsto solo per eventi tradizionali, non per eventi COM. 

Una volta completata questa procedura, viene aggiunta una nuova unit al progetto 
attivo che contiene la definizione per l'oggetto transazionale. Inoltre, il wizard 
aggiunge un progetto di libreria di tipi e la apre nel Type Library editor. A questo 
punto e possibile mostrare le proprieta e i metodi deU'interfaccia tramite la libreria di 
tipi. L'interfaccia viene definita come se si stesse definendo un qualsiasi oggetto 
COM, secondo le modalita descritte in "Definizione deU'interfaccia di un oggetto 
COM" a pagina 41-9. 

L'oggetto transazionale implementa un'interfaccia duale, che supporta sia il binding 
anticipato (in fase di compilazione) tramite vtable, sia il binding differito (in fase di 
esecuzione) tramite l'interfaccia IDispatch. 

L'oggetto transazionale generato implementa i metodi deU'interfaccia IObjectControl, 
Activate, Deactivate e CanBePooled. 

Non e strettamente necessario utilizzare il Transactional Object wizard. E possibile 
convertire qualsiasi oggetto Automation in un oggetto transazionale COM+ (e 
qualsiasi oggetto Automation in-process in un oggetto transazionale MTS) 
utilizzando la pagina COM+ del Type Library editor ed installando poi l'oggetto in 
un package MTS o in un'applicazione COM+. Tuttavia, il Transactional Object 
wizard offre alcuni benefici: 

• Implementa automaticamente l'interfaccia IObjectControl, aggiungendo all'oggetto 
gli eventi OnActivate e OnDeactivate, in modo da consentire la creazione di gestori 
di evento che rispondano al momento dell'attivazione o disattivazione 
dell'oggetto. 

• Genera automaticamente un membro m_spObjectContext semplificando cosi 
all'oggetto l'accesso ai metodi di IObjectContext per controllare l'attivazione e le 
transazioni. 

Scelta di un modello di threading per un oggetto transazionale 



L'ambiente di runtime MTS o COM+ gestisce automaticamente i thread. Gli oggetti 
transazionali non creano thread. Inoltre non devono mai interrompere un thread che 
effettua una chiamata in una DLL. 
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Quando nel Transactional object wizard si specifica il modello di threading, si 
specifica come gli oggetti vengono assegnati ai thread per l'esecuzione dei metodi. 



Tabella 44.2 Modelli di threading per oggetti transazionali 
Modello di 



Single 



Descrizione 



Vantaggi e svantaggi 
dell'implementazione 



Non supporta alcun thread. Le 
richieste del client vengono 
serializzate tramite il meccanismo 
di chiamata. 

Tutti gli oggetti di un componente 
single-threaded vengono eseguiti 
sul thread principale. 

Questo e compatibile con il 
modello di threading COM 
predefinito, che viene usato per i 
componenti che non hanno un 
attributo Threading Model 
Registry o per i componenti COM 
che non sono rientranti. 
L'esecuzione del metodo viene 
serializzata in tutti gli oggetti del 
componente e in tutti i componenti 
di un processo. 



Consente ai componenti di usare le 
librerie che non sono rientranti. 

Scalabilita molto limitata. 

I componenti a thread singolo con 
stato sono soggetti a blocchi critici. E 
possibile eliminare questo problema 
usando oggetti senza stato e 
chiamando SetComplete prima di 
ritornare da un qualsiasi metodo. 



Apartment 

(or Single-threaded 

apartment) 



Ogni oggetto viene assegnato ad 
un thread, che vale per l'intera 
durata dell'oggetto; comunque, si 
possono usare piu thread per piu 
oggetti. Questo e un modello COM 
standard di simultaneity. Ogni 
apartment viene collegato ad un 
specifico thread ed ha una sorgente 
di messaggi Windows. 



Fornisce miglioramenti significativi 
rispetto alia concorrenza nel modello 
di threading Single. 

Due oggetti possono essere eseguiti 
contemporaneamente finche non 
svolgono la stessa attivita. 

Simile ad un apartment COM, tranne 
per il fatto che gli oggetti possono 
essere distribuiti su piu processi. 



Both 



Identico ad Apartment, tranne per 
il fatto che le calback ai client sono 
serializzate. 



Stessi vantagggi di Apartment. 
Inoltre, questo modello e necessario 
nel caso si voglia usare l'Object 
Pooling. 



Questi modelli di threading sono simili a quelli definiti dagli oggetti COM. Tuttavia, 
poiche l'ambiente MTS e COM+ forniscono un maggiore supporto di base per i 
thread, il significato di ciascun modello di threading qui e diverse Inoltre, i modelli 
free threading non si applicano agli oggetti transazionali a causa del supporto 
residente delle attivita. 

Attivita 

Oltre al modello di threading, gli oggetti transazionali supportano la concorrenzialita 
tramite le attivita. Le attivita sono registrate nel contesto dell'oggetto e l'associazione 
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tra un oggetto ed un'attivita non puo essere cambiata. Un'attivita include l'oggetto 
transazionale creato dal client base, oltre a tutti gli oggetti MTS creati da 
quell'oggetto e dai suoi discendenti. Questi oggetti possono essere distribuiti in uno 
o piu processi, che vengono eseguiti su uno o piu computer. 

Per esempio, l'applicazione clinica per i medici puo avere un oggetto transazionale 
per aggiungere gli aggiornamenti e rimuovere i record ai vari database medici, 
ciascuno rappresentato da un oggetto diverse Questo record aggiunto puo usare 
anche altri oggetti, come un oggetto ricezione per registrare la transazione. Cio 
genera diversi oggetti transazionali che sono direttamente o indirettamente sotto il 
controllo di un client base. Questi oggetti appartengono tutti alia stessa attivita. 

MTS o COM+ tengono la traccia del flusso d'esecuzione in ciascuna attivita, 
impedendo cosi che il parallelismo involontario danneggi lo stato dell'applicazione. 
Questa caratteristica genera un singolo thread logico di esecuzione per tutta una serie 
di oggetti potenzialmente distribuiti. Avendo un thread logico, le applicazioni sono 
notevolmente piu facili da scrivere. 

Quando un oggetto transazionale viene creato da un contesto esistente, tramite un 
oggetto contestuale di transazione o un contesto di oggetto, il nuovo oggetto diventa 
un membro della stessa attivita. In altre parole, il nuovo contesta eredita 
l'identificatore di attivita del contesto usato per crearlo. 

E permesso solo un singolo thread logico di esecuzione all'interno dell'attivita. 
Questo comportamento e simile a quello di un modello di threading COM di tipo 
apartment, tranne per il fatto che gli oggetti possono essere distribuiti in piu processi. 
Quando un client base chiama in un'attivita, tutte le altre richieste di lavoro 
dell'attivita (provenienti, per esempio, da un altro thread del client) vengono bloccate 
finche il thread iniziale di esecuzione non ritorna di nuovo al client. 

In ambiente MTS, ogni oggetto transazionale appartiene a un'attivita. In ambiente 
COM+, e possibile configurare il modo in cui l'oggetto partecipa alle attivita 
impostando la sincronizzazione della chiamata. Sono disponibili le opzioni 
seguenti: 

Tabella 44.3 Opzioni di sincronizzazione della chiamata 
Opzione Significato 

Disabled COM+ non assegna attivita all'oggetto ma puo ereditarle col contesto del 

chiamante. Se il chiamante non ha alcuna transazione o contesto di oggetto, 
l'oggetto non viene assegnato a un'attivita. II risultato e come se l'oggetto non 
fosse installato nell'applicazione COM+. Questa opzione non si dovrebbe 
utilizzare se un qualsiasi oggetto nell'applicazione utilizza un manager di 
risorse o se l'oggetto supporta transazioni o attivazione just-in-time. 

Not Supported COM+ non assegna mai l'oggetto a un'attivita, indipendentemente dallo stato 
del suo chiamante. Questa opzione non si dovrebbe utilizzare se un qualsiasi 
oggetto nell'applicazione utilizza un manager di risorse o se l'oggetto 
supporta transazioni o l'attivazione just-in-time. 

Supported COM+ assegna l'oggetto alia stessa attivita del suo chiamante. Se il chiamante 

non appartiene a un'attivita, anche l'oggetto si comportera in modo analogo. 
Questa opzione non si dovrebbe utilizzare se un qualsiasi oggetto 
nell'applicazione utilizza un manager di risorse o se l'oggetto supporta 
transazioni o l'attivazione just-in-time. 
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Tabella 44.3 Opzioni di sincronizzazione della chiamata 



Opzione 


Significato 


Required 


COM+ assegna sempre l'oggetto a un'attivita, creandone una se occorre. 




Questa opzione si deve utilizzare se l'attributo di transazione e Supported o 




Required. 


Requires New 


COM+ assegna sempre l'oggetto a una nuova attivita, distinta da quella del 




suo chiamante. 



Generazione di eventi in ambiente COM+ 



Molte tecnologie basate su COM, come il motore di script di ActiveX e i controlli 
ActiveX, utilizzano i convogliatori di eventi e le interfacce dei punti di connessione di 
COM per generare eventi. I convogliatori di eventi e i punti di connessione sono 
esempi di un modello ad eventi molto unito. In tale modello, le applicazioni che 
generano eventi (detti publisher nella terminologia COM+ e convogliatori nella 
precedente terminologia COM) sono consapevoli di quali sono le applicazioni che 
rispondono agli eventi (dette subscriber), e vice versa. La durata dei publisher e dei 
subscriber coincide; essi devono essere attivi contemporaneamente. La raccolta di 
subscriber e il meccanismo che notifica loro il verificarsi degli eventi, devono essere 
gestiti e implementati nel publisher. 

COM+ ha introdotto un nuovo sistema per la gestione degli eventi. Invece di 
appesantire ogni publisher con la gestione e con la notifica di ciascun subscriber, 
interviene il sistema sottostante (COM+) e prende il controllo di questo processo. II 
modello a eventi di COM+ e scarsamente interdipendente, consentendo lo sviluppo, 
la distribuizione e l'attivazione di publisher e subscriber in modo indipendente l'uno 
dall'altro. 

Benche il modello a eventi di COM+ semplifichi notevolmente la comunicazione fra 
publisher e subscriber, introduce anche alcune attivita amministrative aggiuntive per 
gestire il nuovo strata di software che ora esiste tra di loro. Le informazioni sugli 
eventi e sui subscriber sono conservate in una parte del COM+ Catalog detta anche 
event store. Per eseguire questi compiti amministrativi vengono utilizzati strumenti 
come Component Services Manager. Lo strumento Component Services supporta 
completamente gli script, consentendo l'automazione di gran parte dei compiti 
amministrativi. Ad esempio, una procedura di installazione potrebbe eseguire queste 
operazioni durante la sua esecuzione. Inoltre, l'event store puo essere gestito da 
programma utilizzando l'oggetto TComAdminCatalog. I componenti COM+ possono 
essere installati anche direttamente da C++Builder, selezionando il comando Run I 
Install COM+ object. 

Come nel caso del modello a eventi strettamente interdipendenti, un evento e 
semplicemente un metodo in un'interfaccia. Pertanto, e necessario per prima cosa 
creare un'interfaccia per i metodi dell'evento. E possibile utilizzare COM+ Event 
Object wizard di C++ Builder per creare un progetto contenente un oggetto evento di 
COM+. Quindi, utilizzando lo strumento amministrativo Component Services (o 
TComAdminCatalog o 1'IDE), creare un'applicazione COM+ che contenga un 
componente della classe evento. Quando si crea nell'applicazione COM+ il 
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componente della classe evento, si selezionera l'oggetto evento. La classe evento e il 
collante utilizzato da COM+ per collegare il publisher alia lista dei subscriber. 

La cosa interessante su un oggetto evento di COM+ e che esso non contiene alcuna 
implementazione dell'interfaccia dell'evento. Un oggetto evento di COM+ definisce 
semplicemente l'interfaccia che utilizzeranno i publisher e i subscriber per 
comunicare. Quando si crea con C++Builder un oggetto evento di COM+, per 
definire l'interfaccia si utilizzera il Type Library editor. L'interfaccia viene 
implementata quando si crea un'applicazione COM+ e il relativo componente della 
classe evento. La classe evento, quindi, contiene un riferimento e consente laccesso 
aH'implementazione fornita da COM+. In esecuzione, il publisher crea un'istanza 
della classe evento con i soliti meccanismi COM (per esempio CoCreatelnstance). 
L'implementazione COM+ dell'interfaccia e tale per cui tutto cio che un publisher 
deve fare e chiamare un metodo dell'interfaccia (attraverso l'istanza della classe 
evento) per generare un evento che notofichera a tutti i subscriber. 

Nota: Un publisher non deve essere necessariamente esso stesso un componente 
COM. Un publisher e semplicemente una qualsiasi applicazione che crea un'istanza 
della classe evento e genera eventi chiamando i metodi presenti nell'interfaccia 
dell'evento. 

Anche il componente subscriber deve essere installato nel COM+ Catalog. Anche in 
questo caso, l'operazione puo essere svolta sia da programma utilizzando 
TComAdminCatalog, sia dall'IDE sia mediante lo strumento amministrativo gestione 
Component Services. II componente subscriber puo essere installato in 
un'applicazione separata COM+ oppure puo essere installato nella stessa 
applicazione utilizzata per contenere il componente della classe evento. Dopo avere 
installato il componente, per ogni interfaccia di evento supportata dal componente si 
deve creare una subscription. Dopo avere creato la subscription, selezionare quelle 
classi evento (cioe i publisher) che si desidera siano ricevute dal componente. Un 
componente subscriber puo selezionare singole classi evento oppure tutte le classi 
evento. 

A differenza dell'oggetto evento di COM+, un oggetto subscription di COM+ 
contiene la propria implementazione di un'interfaccia di evento; questa e la 
posizione in cui viene svolto il lavoro effettivo per rispondere all'evento nel 
momentoin cui viene generate II COM+ Event Subscription Object wizard di C++ 
Builder puo essere utilizzato per creare un progetto che contiene un componente 
subscriber. 
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La figura seguente rappresenta l'interazione fra publisher, subscriber e il Catalog di 
COM+: 

Figura 44.1 II sistema a eventi di COM+ 



Publisher 



Generate 
event 



TCOMAdminCatalog or Component Services tool 



COM+ Catalog 



Event Store 



Manages 



COM+ Application 




Event Class 



Instantiates 



V 



COM+ Application 



Subscription 



COM+ Events 



Delivers 
event 



Event 
Interface 




Subscriber 



^ 

=^>0 -( Event Object ) 

Event 
Interface 



Uso di Event Object wizard 



E possibile creare oggetti event utilizzando Event Object wizard. II wizard per prima 
cosa controlla se il progetto corrente contiene del codice di implementazione, in 
quanto i progetti che contengono oggetti evento di COM+ non includono 
un' implementazione. Possono contenere solamente definizioni dell'oggetto 
evento. (In un singolo progetto e possibile, tuttavia, includere piu oggetti evento di 
COM+) 

Per attivare Event Object wizard: 

1 Scegliere il comando File I New I Other. 

2 Selezionare la pagina ActiveX. 

3 Fare doppio clic sull'icona COM+ Event Object. 

Nell'Event Object wizard, specificare il nome dell'oggetto evento, il nome 
dell'interfaccia che definisce i gestori di evento e (facoltativamente) una breve 
descrizione degli eventi. 
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All'uscita, il wizard crea un progetto contenente una libreria di tipi che definisce 
l'oggetto evento e la sua interfaccia. Utilizzare il Type Library editor per definire i 
metodi di quell'interfaccia. Questi metodi sono i gestori di evento che i client 
implementano per rispondere agli eventi. 

II progetto dell'oggetto evento include il file di progetto, la unit _ATL per importare 
le classi del modello ATL, e la unit _TLB per definire le informazioni della libreria di 
tipi. Non include una unit di implementazione, comunque, in quanto gli oggetti 
evento di COM+ non hanno implementazione. L'implementazione dell'interfaccia e 
a carico del client. Quando l'oggetto server chiama un oggetto evento di COM+, 
COM+ intercetta la chiamata e l'invia ai client registrati.Poiche gli oggetti evento di 
COM+ non richiedono l'oggetto implementazione, tutto cio che si deve fare dopo 
avere definito l'interfaccia dell'oggetto nel Type Library editor e compilare il 
progetto e installarlo in COM+. 

COM+ impone alcune restrizioni sulle interfacce degli oggetti evento. L'interfaccia 
che si definisce nel Type Library editor per l'oggetto evento deve rispettare le 
seguenti regole: 

• L'interfaccia dell'oggetto evento deve derivare da IDispatch. 

• Tutti i nomi di metodo devono essere unici in tutte le interfacce dell'oggetto 
evento. 

• Tutti i metodi sull'interfaccia dell'oggetto evento devono restituire un valore 
HRESULT. 

• II modificatore per tutti i parametri dei metodi deve essere [in]. 

Uso di COM+ Event Subscription object wizard 



E possibile creare il componente subscriber utilizzando C++Builder COM+ 
Subscription Object wizard. Per attivare il wizard: 

1 Scegliere il comando File I New I Other. 

2 Selezionare la pagina ActiveX. 

3 Fare doppio clic sull'icona COM+ Subscription Object. 

Nella finestra di dialogo del wizard, immettere il nome della classe che implementera 
l'interfaccia dell'evento. Scegliere dalla casella combinata il modello di threading. 
Nel campo Interface, e possibile immettere il nome dell'interfaccia dell'evento, 
oppure e possibile fare clic sul pulsante Browse per attivare una lista di tutte le classi 
evento attualmente installate nel Catalog di COM+. Anche la finestra di dialogo 
COM+ Event Interface Selection contiene un pulsante Browse. E possibile utilizzare 
questo pulsante per cercare e selezionare una libreria di tipi che contenga l'interfaccia 
dell'evento. Quando si seleziona una classe evento esistente (o si immette la libreria), 
il wizard dara la possibility di implementare automaticamente l'interfaccia 
supportata da quella classe evento. Se si seleziona la casella di controllo Implement 
Existing Interface, il wizard creera automaticamente tutti i metodi nell'interfaccia. E 
possibile decidere di fare implementare al wizard le interfacce ereditate selezionando 
la casella di controllo Implement Ancestor Interfaces. Tre interfacce dell'antenato non 
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vengono mai implementate dal wizard: IUnknown, IDispatch e IAppServer. Per 
completare il wizard, immettere una breve descrizione del componente subscriber 
dell'evento e fare clic su OK. 



Attivazione di eventi utilizzando un oggetto evento di COM+ 



Per generare un evento, un publisher crea per prima cosa un'istanza della classe 
evento, con i soliti meccanismi COM (per esempio CoCreatelnstance). E bene ricordare 
che la classe evento contiene la propria implementazione dell'interfaccia dell'evento, 
e pertanto la generazione di un evento non e altro che la semplice chiamata del 
metodo appropriate dell'interfaccia. 

A questo punto subentra il sistema a eventi di COM+. La chiamata al metodo di un 
evento fa si che il sistema cerchi tutti i subscriber nel Catalog di COM+ e invii loro 
notifica dell'evento. Dal lato del subscriber, l'evento non sembra essere niente di piu 
di una chiamata al metodo dell'evento. 

Quando un publisher genera un evento, i subscriber ne vengono informati in modo 
sincrono, uno alia volta. Non v'e alcun modo per specificare l'ordine di notifica, ne si 
puo contare sul fatto che l'ordine sia lo stesso ogni volta che viene generato un 
evento. Quando una classe evento e installata nel Catalog di COM+, l'amministratore 
puo selezionare l'opzione FirelnParallel per richiedere che l'evento venga notificato 
utilizzando piu thread. Cio non garantisce la consegna simultanea; e semplicemente 
una richiesta al sistema di consentire che cio possa awenire. 

II valore restituito al publisher e un'aggregazione di tutti i codici restituiti da ogni 
subscriber. II publisher non ha alcun modo diretto per scoprire quale subscriber non 
e andato a buon fine. Per fare cio, un publisher deve implementare un filtro di 
publisher. Per ulteriori informazioni su questo argomento, consultare la 
documentazione MSDN di Microsoft. La tabella seguente riassume i codici derivanti 
dalla scelta di varie combinazioni: 



Tabella 44.4 Codici di ritorno dei publisher di evento 
Codice restituito 

S_OK 

EVENT_S_SOME_SUBSCRIBERS_F AILED 

EVENT_E_ALL_SUBSCRIBERSJF AILED 
EVENT_S_NOSUBSCRIBERS 



Significato 

Tutti i subscriber sono andati a buon fine. 

Non e stato possibile chiamare qualche 
subscriber, oppure alcuni hanno restituito un 
codice di malfunzionamento (notare che questa 
non e una condizione di errore). 

Non e stato possibile chiamare alcun subscriber 
oppure tutti i subscriber hanno restituito un 
codice di malfunzionamento. 

Nel Catalog di COM+ non e'e alcuna 
subscription (notare che questa non e una 
condizione di errore). 
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Passaggio di riferimenti a oggetti 



Le informazioni sul passaggio di riferimenti a oggetti sono valide solo per MTS, non 
per COM+. Questo meccanismo e necessario in ambiente MTS perche e necessario 
garantire che tutti i puntatori agli oggetti che sono in esecuzione in ambiente MTS 
vengano indirizzati attraverso gli interceptor. Poiche gli interceptor sono incorporati 
in COM+, non e necessario passare i riferimenti a oggetti. 

In ambiente MTS, e possibile passare riferimenti a oggetti (da usare, per esempio, 
come callback), solo nei seguenti modi: 

• Tramite il ritorno da un'interfaccia di creazione dell'oggetto, come, per esempio, 
CoCreatelnstance (o un suo equivalente), ITransactionContext::CreateInstance o 
IObjectContext::CreateInstance. 

• Tramite una chiamata a Querylnterface. 

• Tramite un metodo che ha chiamato SafeRef -per ottenere il riferimento oggetto. 

Un riferimento a oggetto ottenuto in uno dei modi sopra riportati viene definito 
riferimento sicuro. I metodi chiamati usando riferimenti sicuri saranno eseguiti con 
assoluta sicurezza all'interno del contesto corretto. 

L'ambiente di esecuzione di MTS vuole che le chiamate utilizzino riferimenti sicuri, 
in modo da gestire le opzioni di contesto e consentire agli oggetti transazionali di 
avere una durata indipendente dai riferimenti del client. I riferimenti sicuri non sono 
necessari in ambiente COM+. 

Uso del metodo SafeRef 

Un oggetto puo usare una funzione SafeRef in modo da ottenere un riferimento sicuro 
a se stesso che consenta di oltrepassare il contesto. Questa funzione e disponibile 
come metodo dell'oggetto TMtsDll; essa controlla se il server e in esecuzione in 
ambiente MTS o COM+ e restituisce, in base a cio, il puntatore opportuno. 

Sa/eRe/accetta come input 

• Un riferimento all'ID (RIID) dell'interfaccia che l'attuale oggetto vuole passare ad 
un altro oggetto o client. 

• AUn riferimento all'interfaccia IUnknown dell'oggetto corrente. 

SafeRef restituisce un puntatore all'interfaccia specif icata nel parametro RIID che 
rende certo il passaggio al di la del contesto dell'oggetto attivo. Questo puntatore 
restituisce NULL se l'oggetto richiede un riferimento sicuro su un oggetto diverso da 
se stesso, o se l'interfaccia richiesta nel parametro RIID non viene implementata. 

Quando un oggetto MTS vuole passare un riferimento a se stesso per un client o per 
un altro oggetto (da usare, per esempio, come callback), prima chiamera sempre 
SafeRef e dopo passera il riferimento restituito da questa chiamata. Un oggetto non 
passera mai un puntatore self, o un riferimento a se stesso ottenuto tramite una 
chiamata interna a Querylnterface, ad un client o a qualsiasi altro oggetto. Una volta 
che un tale riferimento e stato passato f uori dal contesto dell'oggetto, non e piu un 
riferimento valido. 
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La chiamata a SafeRef su un riferimento che e gia sicuro restituisce il riferimento 
stesso non modificato, tranne che il numero di riferimento sull'interfaccia non viene 
incrementato. 

Quando un client chiama Querylnterface su un riferimento sicuro, il riferimento 
restituito al client e un riferimento sicuro. 

Un oggetto che ottiene un riferimento sicuro deve rilasciare tale riferimento quando 
non gli occorre piu. 

Per informazioni dettagliate su SafeRef, consultare l'argomento SafeRef nella 
documentazione Microsoft. 

Callback 

Gli oggetti possono effettuare il callback ai client e agli altri oggetti transazionali. Per 
esempio, e possibile avere un oggetto che crei un altro oggetto. La creazione di un 
oggetto pud passare un riferimento di se stesso all'oggetto creato; tale oggetto puo 
usare poi questo riferimento per chiamare l'oggetto creante. 

Se si sceglie di usare i callback, si devono tenere presenti le seguenti restrizioni: 

• Una chiamata di ritorno al client base o ad un altro package richiede la sicurezza a 
livello di accesso sul client. Inoltre, il client deve essere un server DCOM. 

• I firewall intermedi potrebbero bloccare le chiamate di ritorno al client. 

• II lavoro fatto sul callback viene eseguito nell'ambiente dell'oggetto da chiamare. 
Puo far parte della stessa transazione, di una transazione diversa o di nessuna 
transazione. 

• In ambiente MTS, l'oggetto che crea deve chiamare SafeRef e passare il riferimento 
restituito all'oggetto creato in modo da effettuare una chiamata di ritorno a se 
stesso. 

Debug e collaudo di oggetti transazionali 



E possibile effettuare il debug degli oggetti transazionali locali e remoti. Durante il 
debug di oggetti transazionali, puo essere opportuno disattivare il timeout delle 
transazioni. 

II timeout della transazione imposta per quanta tempo (in secondi) puo rimanere 
attiva una transazione. Le transazioni che sono ancora attive dopo il timeout 
vengono abbandonate automaticamente dal sistema. Per impostazione predefinita, il 
valore del timeout e di 60 secondi. E possibile disattivare il timeout delle transazioni 
specificando un valore 0, il che e utile durante il debug. 

Per informazioni sul debug remoto, consultare l'argomento Remote Debugging nella 
Guida in linea. 

Quando si effettua il collaudo di un oggetto transazionale che si intente eseguire in 
ambiente MTS, puo essere opportuno verificare prima l'oggetto asternamente 
all'ambiente MTS per semplificare l'ambiente di verifica. 
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Durante lo sviluppo di un server, non si puo effettuare di nuovo il build del server 
mentre e ancora in memoria, in quanto si riceverebbe un errore del compilatore del 
tipo "Cannot write to DLL while executable is loaded". Per evitare cio, si possono 
impostare le proprieta del package MTS o dell'applicazione COM+ in modo da 
disattivare il server quando e in stato di attesa. 

Per disattivare il server quando e in stato di attesa: 

1 In MTS Explorer o in COM+ Component Manager, fare clic destro sul package 
MTS o sull'applicazione COM+ in cui e installato l'oggetto transazionale e 
scegliere il comando Properties. 

2 Selezionare la pagina Advanced. 

Advanced determina se il processo del server associato ad un package viene 
eseguito sempre o se viene disattivato dopo un certo lasso di tempo. 

3 Cambiare il valore di timeout su 0, il che disattiva il server quando non ha piu un 
client a cui fornire un servizio. 

4 Fare clic su OK per salvare l'impostazione. 

Installazione di oggetti transazionali 



Le applicazioni MTS sono costituite da un gruppo di oggetti MTS in-process che 
vengono eseguiti in un'unica istanza dell'eseguibile MTS (EXE). Un gruppo di 
oggetti COM che vengono eseguiti tutti nello stesso processo viene chiamato 
package. Una singola macchina puo eseguire molti package differenti, dove ciascun 
package e in esecuzione all'interno di un EXE MTS distinto. 

In ambiente COM+, si opera con un gruppo analogo detto applicazione COM+. In 
un'applicazione COM+ gli oggetti non devono essere necessariamente interni al 
processo e non esiste un ambiente di esecuzione separato. 

E possibile raggruppare i componenti dell'applicazione in un singolo package MTS o 
in un'applicazione COM+ da gestire all'interno di un unico processo. Puo essere 
opportuno distribuire i componenti in piu package MTS o applicazioni COM+ in 
modo da suddividere l'applicazione in piu processi o macchine. 

Per installare oggetti transazionali in un package o in un'applicazione COM+: 

1 Se il sistema supporta COM+, scegliere l'opzione Run I Install COM+ objects. Se il 
sistema non supporta COM+ ma sul sistema e installato MTS, scegliere l'opzione 
Run I Install MTS objects. Se il sistema supporta ne MTS ne COM+, non si vedra 
alcuna opzione di menu per installare gli oggetti transazionali. 

2 Nella finestra di dialogo Install Object, selezionare gli oggetti da installare. 

3 Se si stanno installando oggetti MTS, fare clic sul pulsante Package per ottenere un 
elenco dei package MTS nel sistema. Se si stanno installando oggetti COM+, fare 
clic sul pulsante Application. Indicare il package MTS o l'applicazione COM+ in 
cui si stanno installando gli oggetti. E possibile scegliere l'opzione Into New 
Package o Into New Application per creare un nuovo package MTS o 
un'applicazione COM+ in cui installare l'oggetto. E possibile anche scegliere Into 
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Existing Package o Into Existing Application per installare l'oggetto in un package 
MTS o in un'applicazione COM+ esistente fra quelli elencati. 

4 Scegliere OK per aggiornare il catalogo, rendendo cosi gli oggetti disponibili in 
fase di esecuzione. 

I package MTS possono contenere componenti di piu DLL, e i componenti di una 
singola DLL possono essere installati in package differenti. Tuttavia, un singolo 
componente non puo essere distribuito in piu package. 

Analogamente, le applicazioni COM+ possono contenere componenti inclusi in piu 
eseguibili, e componenti differenti di un singolo eseguibile possono essere installati 
in applicazioni COM+ differenti. 

E possibile anche installare l'oggetto transazionale utilizzando COM+ Component 
Manager o MTS Explorer. Durante l'installazione dell'oggetto con uno di questi 
strumenti, accertarsi di applicare le impostazioni per l'oggetto che appaiono sulla 
pagina COM+ del Type Library editor. Queste impostazioni non vengono applicate 
automaticamente quando non si effettua l'installazione dall'IDE. 



Amministrazione di oggetti transazionali 



Una volta installati degli oggetti transazionali, e possibile amministrare questi 
oggetti di runtime usando MTS Explorer (se sono installati in un package MTS) o 
COM+ Component Manager (se sono installati in un'applicazione COM+). I due 
strumenti sono identici, tranne per il fatto che MTS Explorer opera nell'ambiente di 
esecuzione di MTS e COM+ Component Manager opera su oggetti COM+. 

COM+ Component Manager e MTS Explorer posseggono un'interfaccia utente 
grafica per la gestione e la distribuzione di oggetti transazionali. Utilizzando uno di 
questi strumenti e possibile 

• Configurare oggetti transazionali, package MTS o applicazioni COM+, e ruoli 

• Visualizzare le proprieta dei componenti in un package o in un'applicazione 
COM+ e visualizzare i package MTS o le applicazioni COM+ installati su un 
computer 

• Controllare e gestire le transazioni per gli oggetti che comprendono transazioni 

• Spostare i package MTS o le applicazioni COM+ da un computer all'altro 

• Rendere un oggetto transazionale remoto disponibile per un client locale 

Per informazioni dettagliate su questi strumenti, consultare l'appropriato manuale 
Administrator's Guide di Microsoft. 
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Creazione di componenti custom 

I capitoli inclusi nella sezione "Creazione di componenti custom" presentano i 
concetti e le tecniche necessarie per progettare e implementare componenti custom in 
C++Builder. 



Creazione di componenti custom 



Capitolo 




Introduzione alia 



creazione di 
componenti 



Questo capitolo offre una panoramica sulla progettazione di componenti e sulla 
procedura per la scrittura di componenti per applicazioni C++Builder. Presuppone 
che si abbia familiarita con C++Builder e con i suoi componenti standard. 

• Librerie di classi 

• Componenti e classi 

• Creazione di componenti 

• Cosa mettere in un componente 

• Creazione di un nuovo componente 

• Verifica di componenti non installati 

• Collaudo di componenti installati 

• Installazione di un componente sulla Component palette 

Per informazioni sull'installazione di nuovi componenti, consultare "Installazione di 
package di componenti" a pagina 15-6. 



I componenti di C++Builder fanno tutti parte di due gerarchie di classi note come 
Visual Component Library (VCL) e Component Library for Cross Platform (CLX). La 
Figura 45.1 mostra la relazione delle classi selezionate che compongono la VCL. La 
gerarchia della CLX e simile a quella della VCL ma i controlli Windows sono 
chiamati widget (quindi TWinControl e chiamato TwidgetControl, ad esempio) ed 
esistono altre differenze. Per maggiori informazioni sulla gerarchia delle classi e delle 
relazioni di ereditarieta che intercorrono tra le classi, consultare il Chapter 46, 
"Programmazione object-oriented per gli scrittori di componenti". Per una 
panoramica delle differenze tra la CLX e la VCL, consultare "CLX e VCL" a 
pagina 14-5 per dettagli sui componenti consultare la Guida di riferimento in linea 



Librerie di classi 



della CLX. 
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Componenti e classi 



La classe TComponent e l'antenato comune di ogni componente nella VCL e nalla 
CLX. TComponent fornisce le proprieta e gli eventi minimi necessari a un componente 
per funzionare in C++Builder. I vari settori della libreria forniscono altre capacita piu 
specifiche. 

Figura 45.1 La gerarchia di classi della Visual Component Library 



TObject 

i i I i 

Exception TStream TPersistent TComObject 

i i I i i 

TGraphicObject TGraphic TComponent TCollection TStrings 

i i i I i i 

TApplication TDataSet TMenu TControl TCommonDialog TField 

TGraphicControl TWinControl 



TScrollingWinControl TCustomControl 

Most visual controls 



TForm 

TActiveForm TWinControl. 



TCustomForm ' inherit from 



Quando si crea un componente, esso viene aggiunto alia VCL o alia CLX, derivando 
una nuova classe da uno dei tipi di classe gia esistenti nella gerarchia. 

Componenti e classi 



Dal momento che i componenti sono classi, lo scrittore di componenti lavora con gli 
oggetti a un livello differente da quello dello sviluppatore di applicazioni. La 
creazione di nuovi componenti richiede che si derivino nuove classi. 

In sintesi, esistono due difference principali tra la creazione di componenti e il loro 
utilizzo nelle applicazioni. Nella creazione di componenti: 

• Si ha accesso a parti della classe inaccessibili a chi sviluppa applicazioni. 

• Si aggiungono nuove parti al componente (ad esempio, le proprieta). 

Date queste differenze, chi scrive componenti deve prestare attenzione a un maggior 
numero di convenzioni e pensare attentamente a come i componenti da lui sviluppati 
verranno utilizzati da chi scrive applicazioni. 



Creazione di componenti 



Qualsiasi elemento di programma che si intende gestire in fase di progetto puo 
diventare un componente. Creare un componente significa derivare una nuova classe 
da una esistente. Si puo derivare un nuovo componente in molti modi: 
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Creazione di componenti 



• Modifica di controlli esistenti 

• Creazione di controlli con finestra 

• Creazione di controlli grafici 

• Derivazioni di sottoclassi da controlli Windows 

• Creazione di componenti non visuali 

La Tabella 45.1 riepiloga i vari tipi di componenti e le classi che si possono usare 
come punto di partenza per ciascuna di queste tecniche. 

Tabella 45.1 Punti di partenza per la creazione di componenti 
Per raggiungere questo risultato Cominciare con questo tipo 

Modifica di un componente esistente Qualsiasi componente esistente, come TButton o TListBox, 

oppure un tipo astratto di componente, come 
TCustomListBox 



Creazione di un controllo con 
finestra (o basato su widget in CLX) 

Creazione di un controllo grafico 

Creazione di una sottoclasse da un 
controllo 

Creazione di un componente non 
visuale 



TWinControl {TWidgetControl in CLX) 
TGraphicControl 

Qualsiasi controllo Windows (VCL) o basato su widget 
(CLX) 

TComponent 



Si possono anche derivare classi che non sono componenti e che non possono essere 
gestite su una scheda, come TReglniFile e TFont. 



Modifica di controlli esistenti 



II modo piu semplice per creare un componente consiste nel personalizzarne uno 
esistente. Si puo derivare un nuovo componente da un qualsiasi altro fornito con 
C++Builder. 

Alcuni controlli, come le caselle di riepilogo e le griglie, presentano diverse varianti 
di una stessa impostazione di base. In questi casi, la VCL e la CLX includono una 
classe astratta (il cui nome contiene la parola "Custom", ad esempio TCustomGrid) da 
cui derivare versioni personalizzate. 

Ad esempio, si potrebbe creare una casella di riepilogo speciale, priva di alcune 
proprieta della classe standard TListBox. Non e possibile rimuovere (nascondere) una 
proprieta ereditata da una classe antenato, quindi occorre derivare il componente da 
un oggetto di livello superiore rispetto a TListBox nella gerarchia. Anziche partire 
necessariamente dalla classe astratta TWinControl (o da TWidgetControl nella CLX) e 
reinventare tutte le funzioni della casella di riepilogo, la VCL mette a disposizione 
TCustomListBox, che implementa le proprieta della casella di riepilogo ma non le 
pubblica. Quando si deriva un componente da una classe astratta come 
TCustomListBox, si rendono pubbliche solo le proprieta che si vogliono rendere 
disponibili nel componente, lasciando protetto tutto il resto. 

II Capitolo 47, "Creazione di proprieta", spiega come rendere pubbliche le proprieta 
ereditate. II Capitolo 53, "Modifica di un componente esistente", e il Capitolo 55, 



Introduzione alia creazione di componenti 45-3 



Creazione di component! 

"Personalizzazione di una griglia", mostrano alcuni esempi di come modificare i 
controlli esistenti. 

Creazione di controlli con finestra 



I controlli con finestra nella VCL e nella CLX sono oggetti che appaiono in esecuzione 
e con cui l'utente puo interagire. Ogni controllo con finestra ha un handle di finestra, 
accessibile tramite la proprieta Handle, che consente al sistema operativo di 
identificare il controllo e di operare su di esso. Se si utilizzano controlli VCL, l'handle 
consente al controllo di ricevere il fuoco di input e puo essere passato alle funzioni 
API di Windows. In CLX, questi controlli sono controlli basati su widget. Ogni 
controllo basato su widget ha un handle, accessibile tramite la proprieta Handle, che 
identifica il widget sottostante. 

Tutti i controlli con finestra discendono dalla classe TWinControl (TWidgetControl in 
CLX). Fra questi vi sono numerosi controlli con finestra standard, quali pulsanti, 
caselle di riepilogo e caselle di testo. Benche sia possibile derivare direttamente da 
TWinControl (da TWidgetControl in CLX), un controllo originale (un controllo che non 
e in relazione con nessun altro controllo esistente), C++Builder fornisce 
appositamente per questo scopo il componente TCustomControl. TCustomControl e un 
controllo con finestra specializzato che semplifica il disegno di complesse immagini 
visuali. 

II Capitolo 55, "Personalizzazione di una griglia", presenta un esempio di creazione 
di un controllo con finestra. 

Creazione di controlli grafici 



Se non e necessario che il controllo riceva il fuoco di input, e possibile trasformarlo in 
un controllo grafico. I controlli grafici sono analoghi ai controlli per finestra, ma non 
hanno gli handle di finestra, e pertanto consumano meno risorse di sistema. 
Componenti come TLabel, che non ricevono il fuoco di input, sono controlli grafici. 
Anche se questi controlli non possono ricevere il fuoco, e possibile progettarli in 
modo che rispondano ai messaggi del mouse. 

C++Builder supporta la creazione di controlli personalizzati grazie al componente 
TGraphicControl. TGraphicControl e una classe astratta derivata da TControl. Anche se 
e possibile derivare i controlli direttamente da TControl, e meglio iniziare da 
TGraphicControl, il quale fornisce un canvas su cui disegnare e, in Windows, e in 
grado di gestire i messaggi WM_PAINT; tutto cio che occorre fare e ridef inire il 
metodo Paint. 

II Capitolo 54, "Creazione di un controllo grafico", contiene un esempio di creazione 
di un controllo grafico. 

Derivazioni di sottoclassi da controlli Windows 



Nella programmazione tradizionale in Windows i controlli personalizzati vengono 
creati definendo una nuova classe window e registrandola con Windows. La classe 
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Cosa mettere in un componente 



window (simile agli oggetti o alle classi nella programmazione orientata agli oggetti) 
contiene informazioni condivise tra istanze dello stesso tipo di controllo; e possibile 
basare una nuova classe window su una esistente; questa operazione viene detta 
derivazione di sottoclassi (subclassing). Si inserisce quindi il controllo in una DLL 
(Dynamic Link Library), in modo analogo a quanto si fa per i controlli standard di 
Windows, e gli si fornisce un'interfaccia. 

C++Builder consente di creare un "contenitore" di componenti per qualsiasi classe 
window esistente. Pertanto se si desidera usare nelle applicazioni C++Builder una 
libreria esistente di controlli personalizzati, e possibile creare componenti di 
C++Builder che si comportano come i propri controlli, e derivare i nuovi controlli 
esattamente come si farebbe con qualsiasi altro componente. 

Per esempi delle tecniche usate nei controlli Windows di derivazione delle classi, 
vedere i componenti nel file header StdCtls che rappresentano i controlli Windows 
standard, come TEdit. Per esempi della CLX, vedere QStdCtls. 

Creazione di componenti non visuali 



I componenti non visuali sono utilizzati come interfacce per elementi come database 
(TDataSet o TSQLConnection) e clock di sistema (TTimer), e come segnaposti per le 
finestre di dialogo (TCommonDialog nella VCL o TDialog nella CLX e i relativi 
discendenti). E probabile che quasi tutti i componenti che si scrivono siano controlli 
visuali. I componenti non visuali possono essere derivati direttamente da 
TComponent, la classe base astratta di tutti i componenti. 

Cosa mettere in un componente 



Per far si che i propri componenti siano parti affidabili dell'ambiente C++Builder, e 
necessario seguire determinate convenzioni durante la loro progettazione. Questa 
sezione affronta i seguenti argomenti: 

• Rimozione delle dipendenze 

• Impostazione di proprieta, metodi ed eventi 

• Incapsulamento della grafica 

• Registrazione di componenti 

Rimozione delle dipendenze 



Una qualita che rende i componenti utilizzabili e la totale assenza nel codice di 
restrizioni su cio che possono fare. Per caratteristica intrinseca, i componenti sono 
incorporati all'interno delle applicazioni in combinazioni, ordini e contesti svariati. Si 
dovrebbero progettare componenti che funzionino in qualsiasi situazione, senza 
alcun prerequisite 

Un esempio eccellente di rimozione delle dipendenze e la proprieta Handle di 
TWinControl. Chi ha gia scritto applicazioni Windows sa che uno degli aspetti piu 
difficili e suscettibili di errori nell'esecuzione di un programma e di garantirsi, 
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Cosa mettere in un componente 



chiamando la funzione API CreateWindow, da un tentativo di accesso a una finestra o 
a un controllo finche questi non vengono creati. I controlli per finestra di C++Builder 
evitano all'utente questa preoccupazione assicurando la disponibilita di un handle di 
finestra valido in caso di necessita. II controllo puo verificare se la finestra e stata 
creata utilizzando una proprieta che rappresenta l'handle della finestra; se l'handle 
non e valido, il controllo crea una finestra e restituisce l'handle. In questo modo, ogni 
volta che il codice di un'applicazione accede alia proprieta Handle, si ha la sicurezza 
di ottenere un handle valido. 

Eliminando operazioni di base come la creazione di finestre, i componenti di 
C++Builder consentono agli sviluppatori di concentrarsi su cio che vogliono 
realmente fare. Non c'e alcun bisogno di verificare se l'handle esiste o di creare la 
finestra, prima di passare un handle di finestra a una funzione API. Lo sviluppatore 
di applicazioni puo dare per scontato il normale funzionamento, invece di continuare 
a verificare tutte le cose che possono provocare di errori. 

Per quanta la creazione di componenti liberi da dipendenze richieda molto tempo, di 
solito e tempo ben speso. Non solo risparmia agli sviluppatori di applicazioni 
compiti ripetitivi e faticosi, ma riduce la quantita di documentazione e le incombenze 
del supporto. 

Impostazione di proprieta, metodi ed eventi 



Altre all'immagine visibile che puo essere gestita in Form designer, gli attributi piu 
ovvi di un componente sono le proprieta, gli eventi e i metodi. A ciascuno di questi 
argomenti e dedicate un capitolo; la spiegazione che segue mette in evidenza alcune 
motivazioni che ne giustificano l'utilizzo. 

Proprieta 

Le proprieta danno alio sviluppatore di applicazioni l'impressione di impostare o di 
leggere il valore di una variabile, mentre consentono alio scrittore di componenti di 
nascondere la struttura dati associata o di implementare particolari elaborazioni 
quando si accede al valore. 

Ci sono molti vantaggi nell'utilizzo delle proprieta: 

• Le proprieta sono disponibili in fase di progetto. Chi sviluppa applicazioni puo 
impostare o modificare i valori iniziali delle proprieta senza dover scrivere una 
riga di programma. 

• Le proprieta sono in grado di controllare i valori o i formati non appena vengono 
assegnati dallo sviluppatore di applicazioni. La convalida dell'input in fase di 
progettazione consente di prevenire errori. 

• II componente puo creare su richiesta valori appropriati. L'errore di 
programmazione forse piu frequente e quello di fare riferimento a una variabile 
non inizializzata. Rappresentando i dati con una proprieta, e possibile garantire 
che un valore sia sempre disponibile a richiesta. 
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• Le proprieta consentono di nascondere i dati con un'interfaccia semplice e 
coerente. E possibile modificare la struttura delle informazioni di una proprieta 
senza rendere percepibile il cambiamento a chi sviluppa applicazioni. 

II Capitolo 47, "Creazione di proprieta", spiega come aggiungere proprieta ai 
componenti. 

Eventi 

Un evento e una particolare proprieta che chiama del codice in risposta ad un input o 
ad altra attivita in fase di esecuzione. Gli eventi offrono agli sviluppatori di 
applicazioni un modo per collegare blocchi specifici di codice a occorrenze specifiche 
in fase di esecuzione, come le azioni e la pressione dei tasti del mouse. II codice che 
viene eseguito al verificarsi di un evento e detto gestore di evento. 

Gli eventi consentono a chi sviluppa applicazioni di specificare le risposte per i 
diversi tipi di input, senza dover definire nuovi componenti. 

II Chapter 48, "Creazione di eventi", spiega come implementare gli eventi standard e 
come definirne di nuovi. 

Metodi 

I metodi di una classe sono funzioni che operano su una classe piuttosto che su 
specifiche istanze della classe. Per esempio, ogni metodo costruttore di un 
componente e un metodo della classe. I metodi dei componenti sono funzioni che 
operano sulle stesse istanze dei componenti. Chi sviluppa applicazioni usa i metodi 
per ordinare al componente di compiere un'azione specifica o di restituire un valore 
non contenuto in alcuna proprieta. 

Poiche richiedono l'esecuzione di codice, i metodi possono essere chiamati soltanto 
in fase di esecuzione. I metodi risultano utili per svariati motivi: 

• I metodi incapsulano le funzionalita di un componente nello stesso oggetto in cui 
risiedono i dati. 

• I metodi possono nascondere procedure complesse con un'interfaccia semplice e 
coerente. Lo sviluppatore di applicazioni pud chiamare un metodo AlignControls 
di un componente senza sapere come funziona o quali differenze presenta rispetto 
al metodo AlignControls di un altro componente. 

• I metodi consentono di aggiornare diverse proprieta con una sola chiamata. 

II Capitolo 49, "Creazione di metodi", spiega come aggiungere metodi ai 
componenti. 

Incapsulamento della grafica 



C++Builder semplifica la gestione della grafica in Windows poiche incapsula i vari 
strumenti grafici in un canvas. II canvas rappresenta la superficie di disegno di una 
finestra o di un controllo e contiene altre classi, come una penna, un pennello o un 
font. Un canvas e analogo a un contesto di dispositivo di Windows, ma effettua 
automaticamente la maggior parte della manutenzione. 
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Creazione di un nuovo componenle 



Se si e gia scritta un'applicazione grafica per Windows, si ha familiarita con i requisiti 
imposti dall'interfaccia GDI (Graphics Device Interface) di Windows. Per esempio, la 
GDI limita il numero di contesti disponibili per i dispositivi e richiede che gli oggetti 
grafici vengano ripristinati al loro stato iniziale prima di distruggerli. 

C++Builder evita tutte queste preoccupazioni. Per disegnare su una scheda o su altro 
componente, si accede alia proprieta Canvas del componente. Se si desidera 
personalizzare una penna o un pennello, se ne impostano il colore o lo stile. Al 
termine, C++Builder si sbarazza delle risorse. C++Builder inoltre mette in cache le 
risorse per evitare di ricrearle nel caso l'applicazione utilizzi spesso lo stesso tipo di 
risorse. 

E sempre possibile accedere liberamente alia GDI di Windows, ma non si pud non 
constatare che, se si utilizza il canvas incluso nei componenti di C++Builder, spesso il 
codice e piu semplice e viene eseguito piu velocemente. Le caratteristiche grafiche 
sono spiegate in dettaglio nel Capitolo 50, "Uso della grafica nei componenti". 

L'incapsulamento della grafica della CLX funziona diversamente. Un canvas e invece 
un painter. Per disegnare su una scheda o su altro componente, si accede alia 
proprieta Canvas del componente. Canvas e una proprieta ed e anche un oggetto di 
nome TCanvas. TCanvas funge da wrapper per un oggetto Qt painter a cui e possibile 
accedere attraverso la proprieta Handle. E possibile utilizzare lo handle per accedere a 
funzioni a basso livello delle libreria grafiche di Qt. 

Se si desidera personalizzare una penna o un pennello, se ne impostano il colore o lo 
stile. Al termine, C++Builder si sbarazza delle risorse. CLX inoltre memorizza nella 
cache le risorse. 

E possibile utilizzare il canvas incorporate nei componenti CLX derivandolo da essi. 
II funzionamento delle immagini grafiche dipende dal canvas dell'oggetto da cui il 
componente deriva. 

Registrazione di componenti 



Prima di installare i propri componenti nell'IDE di C++Builder, e necessario 
registrarli. La registrazione comunica a C++Builder dove collocare il componente 
sulla Component palette. E anche possibile personalizzare il modo in cui C++Builder 
registra i componenti nel file di scheda. Per maggiori informazioni sulla registrazione 
di un componente, consultare il Capitolo 52, "Come rendere disponibili i componenti 
in fase di progetto". 

Creazione di un nuovo componente 



Per creare un nuovo componente si puo procedere in due modi: 

• Creazione di un componente con Component wizard 

• Creazione manuale di un componente 

E possibile usare uno di questi due metodi per creare un componente minimamente 
funzionale, pronto per essere installato nella Component palette. Dopo 
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Creazione di un nuovo componente 

l'installazione, si puo aggiungere il nuovo componente ad una scheda e collaudarlo 
sia in fase di progetto sia in fase di esecuzione. In seguito sara possibile aggiungere 
altre caratteristiche al componente, aggiornare la Component palette e continuare il 
collaudo. 

Ci sono diverse operazioni fondamentali da eseguire ogni qualvolta si crea un nuovo 
componente. Questi aspetti vengono descritti di seguito; gli altri esempi riportati in 
questo documento presuppongono una sufficiente padronanza degli argomenti 
trattati. 

1 Creare una unit per il nuovo componente. 

2 Derivare il componente da un altro tipo di componente esistente. 

3 Aggiungere proprieta, metodi e eventi. 

4 Registrare il componente con C++Builder. 

5 Creare un file di Guida per il componente e le relative proprieta, metodi ed eventi. 

La creazione di un file di guida per fornire istruzioni agli utenti sull'uso del 
componente e facoltativa. 

6 Creare un package (una particolare libreria a collegamento dinamico) in modo che 
sia possibile installare il componente nell'IDE di C++Builder. 

Al termine, il componente completo include i seguenti file: 

• Un file package (.BPL) o package collection (.PCE) 

• Una libreria (.LIB) per il package 

• Un file .BPI (Borland Import Library) per il package 

• Un file unit compilato (.OBJ) 

• Un file risorse compilato (.RES) per la mappa della palette 

• Un file di guida (.HLP) 

E anche possibile creare una bitmap per rappresentare il nuovo componente. Vedere 
"Creazione di una bitmap per un componente" a pagina 45-15. 

I rimanenti capitoli della Parte V illustrano i diversi aspetti della costruzione dei 
componenti e forniscono numerosi esempi completi di scrittura di differenti tipi di 
componenti. 

Creazione di un componente con Component wizard 



Component wizard semplifica le fasi iniziali della creazione di un componente. 
Quando si utilizza Component wizard, e necessario specif icare solo quanto segue: 

• La classe da cui il componente e derivato. 

• II nome della classe del nuovo componente. 

• La pagina della Component palette in cui si desidera che appaia. 

• nome della unit in cui il componente verra creato. 

• II percorso di ricerca per trovare la unit. 

• II nome del package in cui si desidera collocare il componente. 

Component wizard esegue le stesse operazioni che si compiono creando un 
componente in modo manuale: 
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• Creazione di una unit (un file .CPP e il file header associato). 

• Derivazione del componente. 

• Dichiarazione di un nuovo costruttore. 

• Registrazione del componente. 

Component wizard non consente di aggiungere componenti a una unit esistente 
(costituita da un file .CPP e dal file header associato). Se si vogliono aggiungere 
nuovi componenti alia unit, occorre farlo manualmente. 

1 Per awiare Component wizard, scegliere uno di questi metodi: 

• Scegliere Component I New Component. 

• Scegliere File I New I Other e fare doppio clic su Component. 

Figura 45.2 Component wizard 

New Component 

l— 

Ancestc 



□ 



Ancestor type: |ff 



3 



Class Name: |TComponent1 



Palette Page: [Samples j^] 
Unit file name: |c:\program liles\borland\cbuilder\Lib\Compone ... | 
path: |$(ECB ]VLib;$(ECE |VEin;$[B CE)M mports;$(ECE]V 



Compilare i campi nel Component wizard: 

2 Specificare nel campo Ancestor Type la classe da cui si sta derivando il nuovo 
componente. 

Nella lista a discesa, molti componenti sono elencati due volte con diversi nomi di 
unit, con uno per la VCL e uno per la CLX. Le unit specifiche della CLX iniziano 
con Q (come QGraphics invece di Graphics). Accertartarsi di effettuare la 
derivazione dal componente corretto. 

3 Specificare nel campo Class Name il nome della classe del nuovo componente. 

4 Specificare nel campo Palette Page la pagina della Component palette in cui 
installare il nuovo componente. 

5 Nel campo Unit file name, specificare il nome della unit in cui si vuole dichiarare 
la classe del componente. 

6 Se la unit non si trova nel percorso di ricerca, modificare il percorso di ricerca nel 
campo Search Path. 

7 Per collocare il componente in un nuovo package o in uno gia esistente, fare clic su 
Component I Install e usare la finestra di dialogo visualizzata per specificare un 
package. 

Se si deriva un componente da una classe VCL o CLX il cui nome inizia con 
"custom" (come TCustomControl), e bene evitare di collocarlo su una scheda finche 
non sono stati ridefiniti tutti i metodi astratti nel componente originale. 
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C++Builder non puo creare oggetti istanza di una classe che ha proprieta o metodi 
astratti. 

8 Dopo aver completato i campi del Component wizard, scegliere OK. C++Builder 
crea una nuova unit formata da un file .cpp e dal relativo file header associato. 

II file .cpp viene visualizzato nel Code editor. II file contiene un costruttore per il 
componente e la funzione Register che registra il componente, dicendo a C++Builder 
quale componente aggiungere alia libreria di componenti e su quale pagina della 
Component palette dovrebbe essere visualizzato. II file contiene inoltre un'istruzione 
include che specifica il file header che e stato creato. Ad esempio: 

♦include <vcl.h> 

♦pragma hdrstop 

♦include "NewCoraponent.h" 

♦pragma package (smart_init ) ; 

// 

// ValidCtrCheck is used to assure that the components created do not have 
// any pure virtual functions. 

// 

static inline void ValidCtrCheck (TNewComponent *) 

{ 

new TNewComponent (NULL) ; 

} 

// 

__fastcall TNewComponent :: TNewComponent (TComponent* Owner) 
: TComponent (Owner) 

{ 
} 

// 

namespace Newcomponent 

{ 

void __fastcall PACKAGE Register () 
{ 

TComponentClass classes [1] = {__classid (TNewComponent) }; 

RegisterComponents ( "Samples", classes, 0); //In CLX use a different page than Samples 

} 

} 

Nel caso di applicazioni CLX, nomi e ubicazioni di alcuni file sono differenti. Ad 
esempio, <vcl\controls .hpp> in CLX diventa <clx\qcontrols.hpp>. 

Per aprire il file header nel Code editor, collocare il cursore sul nome del file header, 
fare clic destro sul pulsante del mouse in modo da visualizzare il menu contestuale e 
scegliere nel menu il comando Open File at Cursor. 

II file header contiene la nuova dichiarazione, composta da una dichiarazione di un 
costruttore e da parecchie istruzioni #include per supportare la nuova classe. Ad 
esempio: 

♦ifndef NewComponentH 
♦define NewComponentH 

// 

♦include <SysUtils .hpp> 
♦include <Controls .hpp> 
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♦include <Classes .hpp> 
♦include <Forms.hpp> 

// 

class PACKAGE TNewComponent : public TComponent 
{ 

private : 
protected : 
public : 

fastcall TNewComponent (TComponent* Owner); 

__published : 

}; 

#endif 

Prima di continuare, salvare il file .cpp assegnandogli un nome significativo. 

Creazione manuale di un componente 



II modo piu semplice per creare un nuovo componente e usare il Component wizard. 
La stessa procedura puo, comunque, essere eseguita anche manualmente. 

Per creare un componente in modo manuale, si devono effettuare le seguenti 
operazioni: 

1 Creazione di un unit file 

2 Derivazione del componente 

3 Dichiarazione di un nuovo costruttore 

4 Registrazione del componente 

Creazione di un unit file 

Una unit di C++Builder e formata da una combinazione di un file .CPP e di un file .H 
che vengono compilati in un file .OBJ. C++Builder utilizza le unit per svariati scopi. 
Ogni scheda ha la propria unit e anche la maggior parte dei componenti (o gruppi 
logici di componenti) ha la propria unit. 

Quando si crea un componente, occorre creare una nuova unit per il componente o 
aggiungere il nuovo componente ad una unit esistente. 

1 Per creare una unit per un componente, scegliere uno dei metodi seguenti: 

• Scegliere il comando File I New I Unit. 

• Scegliere il comando File I New I Other in modo da visualizzare la finestra di 
dialogo New Items, selezionare Unit e scegliere OK. 

C++Builder crea un file .CPP e un file header e visualizza il file .CPP nel Code 
editor. Salvare il file con un nome significativo. 

2 Per aprire il file header, collocare nel Code editor il cursore sul nome del file 
header, fare clic destro e scegliere nel menu contestuale il comando Open File at 
Cursor. 

3 Per aprire una unit esistente, selezionare File I Open e scegliere il codice sorgente 
della unit a cui si desidera aggiungere il componente. 
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Quando un componente viene aggiunto a una unit preesistente, e bene accertarsi 
che questa contenga il codice per i componenti. Per esempio, l'aggiunta del codice 
per un componente ad una unit che contiene una scheda provoca errori nella 
Component palette. 

4 Una volta selezionata per il componente una unit nuova o preesistente, e possibile 
derivare la classe del componente. 

Derivazione del componente 

Ogni componente e una classe derivata da TComponent, da uno dei suoi discendenti 
piu specializzati (come TControl o TGraphicControl) o da una classe di componente 
esistente. II paragrafo"Creazione di componenti" a pagina 45-2 descrive da quale 
classe derivare i diversi tipi di componenti. 

La derivazione di nuove classi viene illustrata in dettaglio nella sezione "Definizione 
di nuove classi" a pagina 46-1. 

Per derivare una classe di componente, aggiungere una dichiarazione di classe al file 
header. 

Una semplice classe di componenti e un componente non visuale derivato 
direttamente da TComponent. 

Per creare una semplice classe di componenti, aggiungere la seguente dichiarazione 
di classe al file header: 

class PACKAGE TNewComponent : public TComponent 
{ 

}; 

La macro PACKAGE viene espansa in un'istruzione che consente di esportare e di 
importare le classi. Si dovrebbero inoltre aggiungere tutte le istruzioni include 
necessarie per specificare i file .HPP richiesti dal nuovo componente. Di seguito sono 
elencate le piu comuni istruzioni include usate di solito: 

♦include <vcl\SysUtils .hpp> 
♦include <vcl\Controls.hpp> 
♦include <vcl\Classes .hpp> 
♦include <vcl\Forms .hpp> 

Finora il nuovo componente non fa nulla di diverso da TComponent. E stato solo 
creato un framework in cui costruire il nuovo componente. 

Dichiarazione di un nuovo costruttore 

Ogni nuovo componente deve avere un costruttore che ridefinisca il costruttore della 
classe da cui e stato derivato. Quando si scrive il costruttore del nuovo componente, 
si deve sempre chiamare il costruttore ereditato. 

All'interno della dichiarazione della classe, dichiarare un costruttore virtuale nella 
sezione public della classe. Per maggiori informazioni sulla sezione public, 
consultare "Controllo deU'accesso" a pagina 46-4. Ad esempio: 

class PACKAGE TNewComponent : public TComponent 
{ 

public: 
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virtual fastcall TNewComponent (TComponent* AOwner); 

}; 

Implementare il costruttore nel file .CPP: 

fastcall TNewComponent : :TNewComponent (TComponent* AOwner): TComponent (AOwner) 

{ 
} 

All'interno del costruttore, va aggiunto il codice che si vuole far eseguire al momento 
della creazione del componente. 

Registrazione del componente 

La registrazione e un semplice procedimento che indica a C++Builder quali 
componenti aggiungere alia libreria di componenti e su quale pagina della 
Component palette dovranno apparire. Per una trattazione dettagliata del processo 
di registrazione, consultare il Capitolo 52, "Come rendere disponibili i componenti in 
fase di progetto". 

Per registrare un componente: 

1 Aggiungere al file .CPP della unit una funzione di nome Register, collocandola 
all'interno di un namespace. II namespace e il nome del file in cui e incluso il 
componente, a cui viene sottratto l'estensione, da scrivere tutto in lettere 
minuscole ad eccezione della prima lettera. 

Ad esempio, il codice seguente esiste all'intemo di un namespace Newcomp, dove 
Newcomp e il nome del file .CPP: 

namespace Newcomp 
{ 

void __fastcall PACKAGE Register!) 

{ 

} 

} 

2 All'interno della funzione Register, dichiarare un open array di tipo 
TComponentClass per contenere l'array dei componenti che si vogliono registrare. 
La sintassi dovrebbe essere simile a quella dell'esempio: 

TComponentClass classes [1] = L_classid(TNewComponent) } ; 

In questo caso, l'array delle classi contiene solo un componente, ma e possibile 
aggiungere all'array tutti i componenti che si vogliono registrare. 

3 All'interno della funzione Register, chiamare RegisterComponents per ciascun 
componente che si vuole registrare. 

RegisterComponents e una funzione che accetta tre parametri: il nome di una pagina 
della Component palette, l'array delle classi dei componenti, e la dimensione - 1 
delle classi dei componenti. Se si sta aggiungendo un componente ad una 
registrazione esistente, e possibile sia aggiungere il nuovo componente agli altri 
nell'istruzione che gia esiste, sia aggiungere una nuova istruzione che chiama la 
funzione RegisterComponents. 



45-14 G u i d a 



alia programmazione 



Creazione di un nuovo componente 

Se tutti i componenti devono essere collocati sulla stessa pagina della Component 
palette, e possibile registrarli con una sola chiamata a RegisterComponents. 

Per registrare un componente di nome TNeiuComponent e collocarlo sulla pagina 
Samples della Component palette, aggiungere al file .CPP della unit che dichiara 
TNeiuComponent la seguente funzione Register: 

namespace Newcomp 
{ 

void __fastcall PACKAGE Register!) 

{ 

TComponentClass classes [1] = {__classid(TNewComponent) }; 
RegisterComponents ("Samples", classes, 0); 

} 

} 

Questa chiamata a Register colloca TNewComponent sulla pagina Samples della 
Component palette. 

Una volta registrato il componente, e possibile collaudarlo e infine installarlo nella 
Component palette. Questa procedura e descritta piu dettagliatamente nella sezione 
"Installazione di un componente sulla Component palette" a pagina 45-20. 

Creazione di una bitmap per un componente 



Quando si crea un nuovo componente, e possibile definire delle bitmap personali per 
i componenti custom. 

1 Scegliere Tools I Image Editor. 

2 Nella finestra di dialogo Image Editor, scegliere File I New I Component Resource 
File (.dcr). 

3 Nella finestra di dialogo untitledl.dcr, fare clic destro su Contents. Scegliere il 
comando New I Bitmap. 

4 Nella finestra di dialogo Bitmaps Properties, modificare entrambe le proprieta 
Width ed Height a 24 pixel. Assicurarsi che sia selezionata l'opzione VGA (16 
colors). Fare clic su OK. 

5 Sotto Contents vengono visualizzati Bitmap e Bitmapl. Selezionare Bitmapl, fare 
clic destro e scegliere Rename. Assegnare alia bitmap lo stesso nome della classe 
del nuovo componente, inclusa la lettera T, utilizzando solo lettere in maiuscolo. 
Ad esempio, se il nuovo nome della classe sara TMyNeivButton, assegnare alia 
bitmap il nome TMYNEWBUTTON. 
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E necessario assegnare un nome usando solo lettere maiuscole, 
indipendentemente da come e scritto il nome assegnato alia classe nella finestra di 
dialogo New Component. 




6 Fare doppio clic su TMYNEWBUTTON per visualizzare una finestra di dialogo 
con una bitmap vuota. 

7 Utilizzare la tavolozza dei colori nella zono inferiore dell'Image Editor per 
progettare l'icona. 

8 Scegliere il comando File I Save As e assegnare al file di risorse (.dcr o .res) lo stesso 
nome di base della unit in cui si vuole venga dichiarata la classe del componente. 
Ad esempio, assgnare al file di risorse il nome MyNewButton.dcr. 

9 Scegliere il comando Component I New Component. Seguire le istruzioni a 
pagina 45-9. Assicurarsi che il sorgente del componente, MyNewButton.cpp, sia 
nella stessa directory di MyNewButton.dcr. 

Per una classe di nome TMyNewButton, Component wizard assegna al sorgente 
del componente, o unit, il nome MyNewButton.cpp collocandolo, per 
impostazione predefinita, nella directory LIB. Fare clic sul pulsante Browse per 
trovare la nuova ubicazione della unit del componente appena generata. 

Se per la bitmap si utilizza un file .res invece di un file .dcr, allora aggiungere un 
riferimento al sorgente del componente per collegare la risorsa. Ad esempio, se il 
nome del file .res e MyNewButton.res, dopo essersi assicurati che i file .cpp e .res 
sono nella stessa directory, aggiungono a MyNewButton.cpp quanto segue: 

ipragma resource "*.res" 

10 Scegliere il comando Component I Install Component per installare il componente 
in un package nuovo o esistente. Fare clic su OK. 

II nuovo package viene generate e poi installato. La bitmap che rappresenta il 
nuovo componente viene visualizzata sulla pagina della Component palette 
indicata nel Component wizard. 
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Verifica di componenti non installati 



Prima di installarlo nella Component palette, si puo verificare il comportamento in 
esecuzione del componente. Cio e particolarmente utile per il debug di nuovi 
componenti appena creati, ma la stessa tecnica si applica a qualsiasi altro 
componente presente o meno nella Component palette. Per informazioni sulla 
verifica di componenti installati, consultare "Collaudo di componenti installati" a 
pagina 45-19. 

La verifica di un componente senza installarlo offre il vantaggio di generare degli 
errori in compilazione che vengono visualizzati solo quando la classe viene 
istanziata. Ad esempio, se si cerca di creare un'istanza di una classe astratta, viene 
generato un errore che indica che occorre eseguire l'overload della pure virtual. 

La verifica di un componente non installato viene seguita simulando le stesse azioni 
che esegue C++Builder quando si seleziona il componente nella tavolozza dei 
componenti e lo si colloca su una scheda. 

Per verificare un componente non installato, procedere come segue: 

1 Creare una nuova applicazione o aprirne una esistente. 

2 Scegliere il comando Project I Add to Project per aggiungere al progetto la unit del 
componente. 

3 Includere il file .H della unit del componente al file header della unit della scheda. 

4 Aggiungere alia scheda un membro dati per rappresentare il componente. 

Questa e una delle principali differenze tra il modo in cui l'utente aggiunge i 
componenti e il modo in cui lo fa C++Builder. Nel primo caso il membro dati viene 
aggiunto alia sezione pubblica in fondo alia dichiarazione della classe della 
scheda. C++Builder lo aggiunge, invece, sopra, nella sezione published della 
dichiarazione della classe da lui gestita. 

Non si devono mai aggiungere i membri dati alia sezione della dichiarazione della 
classe della scheda gestita da C++Builder. Gli elementi di quella sezione della 
dichiarazione della classe corrispondono agli elementi memorizzati nel file della 
scheda. L'aggiunta sulla scheda di nomi di componenti che non esistono puo 
invalidare il file della scheda. 

5 Costruire il componente nel costruttore della scheda. 

Quando si chiama il costruttore del componente, occorre passare un parametro 
che specifichi il proprietario del componente (il componente responsabile della 
distruzione del componente al momento opportuno). Quasi sempre come 
proprietario viene passato this. In un metodo, this e un riferimento alia classe che 
contiene il metodo. In questo caso nel gestore OnCreate della scheda, this fa 
riferimento alia scheda. 

6 Assegnare la proprieta Parent. 

L'impostazione della proprieta Parent e sempre la prima cosa da fare dopo aver 
costruito un controllo. II genitore e il componente che contiene visualmente il 
controllo, che molto spesso e la scheda, ma potrebbe essere una casella o riquadro 
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di gruppo. Normalmente Parent viene impostato a this, cioe, alia scheda. Parent 
deve essere impostata sempre prima delle altre proprieta del controllo. 

7 Impostare qualsiasi altra proprieta del componente nel modo desiderata. 

Si supponga di voler verificare un componente della classe TNewControl in una unit 
denominata NewCtrl. Si deve creare un nuovo progetto, quindi seguire le diverse fasi 
per finire con un file header per la scheda simile a questo: 

// 

♦ifndef TestFormH 
♦define TestFormH 

// 

♦include <vcl\Classes .hpp> 
♦include <vcl\Controls.hpp> 
♦include <vcl\StdCtrls.hpp> 
♦include <vcl\Forms .hpp> 
♦include "NewCtrl. h" 
// 

class TForml : public TForra 

{ 

published: // IDE-managed Components 

private: // User declarations 

public: // User declarations 

TNewControl* NewControll; 

fastcall TForml (TComponent* Owner); 

}; 

// 

extern TForml *Forml; 

// 

♦endif 

L'istruzione #include che include il file NEWCTRL.H parte dall'assunto che il 
componente risieda nella directory del progetto corrente o in una directory elencata 
nel percorso dei file include del progetto. 

Questo e il file .CPP della unit della scheda: 

♦include <vcl\vcl.h> 
♦pragma hdrstop 
♦include "TestForm.h" 
♦include "NewCtrl. h" 

// 

♦pragma package(smart_mit) ; 
♦pragma resource "*.dfm" 
TForml *Forml; 

// 

static inline TNewControl *ValidCtrCheck( ) 

{ 

return new TNewControl (NULL) ; 

} 

// 

fastcall TForml :: TForml (TComponent* Owner) 

: TForm (Owner) 

{ 

NewControll = new TNewControl (this) ; 
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NewControll->Parent = this; 
NewControll->Left = 12; 

} 

// 

namespace Newctrl 
{ 

void __fastcall PACKAGE Register!) 
{ 

TComponentClass classes [1] = {__classid(TNewControl) } ; 
RegisterComponents ( "Samples" , classes, 0); 

} 

} 



Collaudo di componenti installati 



E possibile collaudare il comportamento in fase di progettazione di un componente 
dopo averlo installato nella Component palette. Cio e particolarmente utile per il 
debug di nuovi componenti appena creati, ma la stessa tecnica si applica a qualsiasi 
altro componente presente o meno nella Component palette. Per informazioni su 
come collaudare i componenti che non sono stati ancora installati, consultare il 
paragrafo "Verifica di componenti non installati" a pagina 45-17. 

II collaudo di componenti dopo l'installazione consente di eseguire il debug dei 
componenti che generano eccezioni solamente in fase di progettazione, quando li si 
colloca su una scheda. 

Collaudare un componente installato utilizzando una seconda istanza in esecuzione 
di C++Builder: 

1 Dal menu dell'IDE di C++Builder selezionare il comando Project I Options e sulla 
pagina Directories / Conditional, impostare l'opzione Debug Source Path al file 
sorgente del componente. 

2 Selezionare quindi il comando Tools I Debugger Options. Attivare le eccezioni che 
si desidera tracciare sulla pagina Language Exceptions. 

3 Aprire il file sorgente del componente e impostare dei breakpoint. 

4 Selezionare il comando Run I Parameters e impostare il campo Host Application al 
nome e all'ubicazione del file eseguibile di C++Builder. 

5 Nella finestra di dialogo Run Parameters, fare clic sul pulsante Load per avviare la 
seconda istanza di C++Builder. 

6 A questo punto, trascinare sulla scheda i componenti da collaudare, i quali si 
dovrebbero bloccare ai breakpoint fissati nel codice sorgente. 
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Installazione di un componente sulla Component palette 



La procedure per aggiungere un componente alia Component palette e composta da 
due parti: 

• Rendere disponibili i file sorgente. 

• Aggiunta del componente. 

Rendere disponibili i file sorgente 



Tutti i file sorgente usati da un componente dovrebbero essere collocati nella stessa 
directory. Questi file includono i file di codice sorgente (.CPP e .PAS) e i file binari 
(.DFM, .RES, .RC e .DCR). I file header (.H e .HPP) dovrebbero essere collocati nella 
directory Include (o in una posizione raggiungibile mediante il percorso di ricerca 
globale dell'IDE o specifico del progetto). 

II processo di aggiunta di un componente comporta la creazione di un certo numero 
di file. Questi file vengono collocati automaticamente nelle directory specificate nelle 
opzioni dell'ambiente IDE (usare il comando di menu Tools I Environment Options e 
attivare la pagina Library). I file .LIB dovrebbero essere collocati nella directory di 
output specificata per i file BPI/LIB. Se l'aggiunta di un componente comporta la 
creazione di un nuovo package (in contrasto all'installazione in un package 
esistente), il file .BPL viene collocato nella directory di output relativa ai file BPL e i 
file .BPI nella directory di output BPI/LIB. 

Aggiunta del componente 



Per aggiungere i componenti alia libreria di componenti: 

1 Scegliere il comando Component I Install Component. 
Verra visualizzata la finestra di dialogo Install Component. 

2 Decidere se installare il nuovo componente in un package esistente o in uno nuovo 
selezionando la pagina appropriata. 

3 Immettere il nome del file .CPP contenente il nuovo componente oppure scegliere 
il pulsante Browse per trovare la unit. 

4 Se il file .CPP non e nella posizione predefinita mostrata, modificare il percorso di 
ricerca del nuovo componente. 

5 Immettere il nome del nuovo package in cui installare il componente oppure 
scegliere il pulsante Browse per trovare il package. 

6 Se il componente viene installato in un nuovo package, se si vuole, e possibile 
immettere una descrizione significativa del package. 

7 Scegliere OK per chiudere la finestra di dialogo Install Component. Cosi facendo il 
package viene compilato e generato e il componente installato sulla Component 
palette. 
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I componenti appena installati appaiono inizialmente sulla pagina della Component 
palette specificata da chi ha scritto il componente. Una volta installati nella tavolozza, 
e possibile spostare i componenti su una pagina differente utilizzando la finestra di 
dialogo Component I Configure palette. 
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Capitolo 




Programmazione object-oriented per 

gli scrittori di componenti 

Chi ha gia scritto applicazioni con C++Builder, sa che una classe contiene sia dati sia 
codice, e che e possibile manipolare le classi sia in progettazione sia in esecuzione. 

In questo senso, si e un utente di componenti.Quando si creano nuovi componenti, si 
opera con le classi con modalita che non saranno mai necessarie a chi sviluppa 
applicazioni. Si cerca anche di nascondere tutte le operazioni interne del componente 
agli sviluppatori che ne faranno uso. Scegliendo per il componente un antenato 
appropriate progettando le interfacce in modo che espongano solo proprieta e 
metodi necessari alio sviluppatore e seguendo le altre direttive descritte in questo 
capitolo, si potranno creare versatili componenti riutilizzabili. 

Prima di iniziare a creare componenti, si dovrebbe gia avere familiarita con gli 
argomenti, relativi alia programmazione orientata agli oggetti (OOP), elencati di 
seguito): 

• Definizione di nuove classi 

• Antenati, discendenti e gerarchie della classe 

• Controllo dell'accesso 

• Dispatch dei metodi 

• Membri astratti di classi 

• Classi e puntatori 

Definizione di nuove classi 



La differenza tra chi scrive componenti e chi sviluppa applicazioni e che lo scrittore 
di componenti crea nuove classi mentre lo sviluppatore di applicazioni tratta istanze 
di classi. 

Una classe e essenzialmente un tipo. II programmatore lavora sempre con tipi e con 
istanze, anche se non utilizza questa terminologia. Crea, ad esempio, variabili di un 
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tipo, come gli int. Le classi sono di solito piu complesse dei tipi semplici di dati, ma il 
loro modo di operare e lo stesso: l'assegnazione di valori differenti a istanze dello 
stesso tipo permette di eseguire compiti diversi. 

Ad esempio, e piuttosto comune creare una scheda che contiene due pulsanti, uno 
identificato con OK e uno con Annulla. Entrambi sono istanze della classe TButton, 
ma il loro diverso comportamento dipende dall'assegnazione di valori differenti alle 
proprieta Caption e di gestori diversi ai loro eventi OnClick. 

Derivazione di nuove classi 



Ci sono due ragioni per derivare una nuova classe: 

• Modificare le impostazioni predefinite della classe per evitare ripetizioni 

• Aggiungere nuove capacita a una classe 

In entrambi i casi, il file e quello di creare oggetti riutilizzabili. Chi progetta 
componenti pensando al riutilizzo, puo risparmiare in seguito molto lavoro. Si diano 
pure dei valori predefiniti utilizzabili, ma e bene renderli personalizzabili. 

Modificare le impostazioni predefinite della classe per evitare ripetizioni 

Molti programmatori tentano di evitare le ripetizioni. Chi scopre di riscrivere sempre 
le stesse righe di codice, puo collocare il codice in una funzione o creare una libreria 
di routine utilizzabili in diversi programmi. Per i componenti si puo fare lo stesso. Se 
ci si accorge che si variano sempre le stesse proprieta o si fanno le stesse chiamate ai 
metodi, e possibile creare un nuovo componente che faccia queste cose come 
impostazione predefinita. 

Per esempio, si supponga che ogni volta che si crei un'applicazione, si aggiunga una 
finestra di dialogo per compiere una particolare operazione. Si puo progettare una 
volta per tutte la finestra di dialogo, si possono impostarne le proprieta e si puo 
installare nella Component palette un componente wrapper ad esso associato. Si puo 
progettare una volta per tutte la finestra di dialogo, si possono impostarne le 
proprieta e si puo installare nella Component palette un componente wrapper ad 
esso associato. Trasformando la finestra di dialogo in un componente riutilizzabile, 
non solo si elimina un lavoro ripetitivo, ma si incoraggia la standardizzazione e si 
riduce la probability di commettere errori ogni volta che si crea la finestra di dialogo. 

II Capitolo 53, "Modifica di un componente esistente", mostra un esempio di come 
modificare le proprieta predefinite di un componente. 

Se si vogliono modificare solo le proprieta rese pubbliche di un componente 
esistente, oppure per salvare determinati gestori di evento di un componente o di un 
gruppo di componenti, potrebbe risultare conveniente creare un modello di 
componente che semplifica tali operazioni. 

Aggiungere nuove capacita a una classe 

Un motivo abbastanza comune che induce a creare nuovi componenti e l'aggiunta di 
capacita non presenti in componenti esistenti. Per fare cio, si derivi il nuovo 
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componente da un componente esistente o da una classe base astratta, come 
TComponent o TControl. 

E bene derivare il nuovo componente dalla classe che contiene il sottoinsieme di 
caratteristiche piu simili a quelle volute. Si possono aggiungere capacita a una classe 
ma non toglieme; percio se una classe di componente esistente contiene proprieta che 
non devono essere incluse nel nuovo componente, lo si dovrebbe derivare 
dall'antenato di quel componete. 

Ad esempio, per aggiungere funzionalita a una casella di riepilogo, si potrebbe 
derivare il componente da TListBox. D'altra parte, per aggiungere nuove 
caratteristiche ma escludere alcune capacita standard della casella di riepilogo, e 
necessario derivare il componente da TCustomListBox, antenato di TListBox. In questo 
modo e possibile ricreare (o rendere visibili) solo le capacita desiderate della casella 
di riepilogo e aggiungere le nuove caratteristiche. 

II Capitolo 55, "Personalizzazione di una griglia", mostra un esempio di 
personalizzazione di una classe di componente astratta. 

Dichiarazione di una nuova classe di componente 



Oltre ai componenti standard, C++Builder mette a disposizione molte classi astratte 
progettate come basi per derivare nuovi componenti nuovi. La Tabella 45.1 a 
pagina 45-3 mostra le classi da cui e possibile partire per creare i propri componenti. 

Per dichiarare una nuova classe di componenti aggiungere una dichiarazione di 
classe nel file header del componente. 

Per esempio, questa e la dichiarazione di un semplice componente grafico: 

class PACKAGE TSampleShape : public TGraphicControl 
{ 

public: 

virtual fastcall TSampleShape (TComponent* Owner); 

}; 

Non dimenticare di includere la macro PACKAGE (definita in Sysmac.h) che 
consente di importare ed esportare le classi. 

Una dichiarazione completa di componente include proprieta, membri dati e 
dichiarazioni dei metodi prima della parentesi graffa finale, ma anche una 
dichiarazione vuota e valida e rappresenta un punto di partenza per aggiungere le 
caratteristiche del componente. 

Antenati, discendenti e gerarchie della classe 



Chi sviluppa applicazioni parte dall'assunto che ogni controllo abbia proprieta di 
nome Top e Left che determinano la posizione del controllo sulla scheda. Non gli 
interessa che tutti i controlli ereditino queste proprieta da un antenato comune, nella 
fattispecie TControl. Nel creare un componente, tuttavia, occorre sapere da quale 
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classe derivarlo affinche erediti le caratteristiche adatte. Ed e bene sapere tutto cio 
che il controllo eredita, per sfruttare tutte le caratteristiche ereditate senza doverle 
impostare di nuovo. 

La classe da cui si deriva un componente e detta antenato immediato. Ogni 
componente eredita dal suo antenato immediato, dall'antenato dell'antenato e cosi 
via. Tutte delle classi da cui un componente eredita sono dette essere i suoi antenati; 
il componente e un discendente dei suoi antenati. 

Tutte assieme, le relazioni antenato-discendente in un'applicazione costituiscono una 
gerarchia di classi. Ogni generazione nella gerarchia contiene molte piu cose rispetto 
ai propri antenati, dal momento che ogni classe eredita tutto cio che hanno gli 
antenati e aggiunge nuove proprieta e metodi o ridefinisce quelli esistenti. 

Se non si specifica un antenato immediato, C++Builder deriva il componente 
dall'antenato predefinito, TObject. TObject e l'antenato di tutte le classi della 
gerarchia dell'oggetto. 

La regola generale per scegliere l'oggetto da cui derivare un altro oggetto e semplice: 
si deve selezionare l'oggetto che contenga quanto piu possibile di cio che si vuole 
includere nel nuovo oggetto, ma che non includa alcunche di cio che non si vuole nel 
nuovo oggetto. E sempre possibile aggiungere all'oggetto nuove cose, ma non e 
possibile toglierne. 



Controllo dell'accesso 



There Esistono cinque livelli di controllo di accesso-detto anche visibilita-su proprieta, 
metodi e membri dati. La visibilita determinano quale codice puo accedere a quali 
parti della classe. Specificando la visibilita, si definisce Yinterfaccia al componente. 

La Tabella 46.1 mostra i livelli di visibilita, dal piu restrittivo al piu accessibile: 



Tabella 46.1 Livelli di visibilita aM'interno di un oggetto 
Visibilita Significato 

private Accessibile solo nella classe in cui e 

definite 

protected Accessibile solo nella classe in cui e 

definito e nei suoi discendenti. 



Utilizzato per 

Occultamento dei dettagli implementativi. 

Definizione dell'interfaccia per lo scrittore 
di component!. 



public 

automated 



_published 



Accessibile a tutto il codice. 

Accessibile a tutto il codice. Le 
informazioni di tipo automation 
vengono generate. 

Accessibile a tutto il codice e 
dall'Object Inspector. Memorizzata 
in un file scheda. 



Definizione dell'interfaccia di esecuzione. 
Solo OLE Automation. 



Definizione dell'interfaccia di 
progettazione. 
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Occultamento dei dettagli implementativi 



La dichiarazione di una parte di una classe come private, rende quella parte 
invisibile al codice esterno a meno che le funzioni non siano dichiarate friends della 
classe. Le parti private di una classe sono utili soprattutto per nascondere i dettagli 
implementativi agli utenti della classe. Poiche gli utenti della classe non possono 
accedere alle parti private, e possibile cambiare l'implementazione interna della 
classe senza alcuna influenza sul codice dell'utente. 

Se non si specifica alcun controllo di accesso su un membro dati, su un metodo o su 
una proprieta, tale parte risulta private. 

Di seguito e riportato un esempio, suddiviso in due parti, che illustra come il fatto di 
dichiarare private un membro dati impedisca agli utenti di accedere alle 
informazioni. 

La prima parte e una unit di una scheda costituita da un file header e da un file .CPP 
che, nel gestore di evento OnCreate della scheda, assegna un valore a un membro dati 
private Poiche il gestore di evento viene dichiarato all'interno della classe 
TSecretForm, la unit viene compilata senza errori. 

♦lfndef HidelnfoH 
♦define HidelnfoH 

// 

♦include <vcl\SysUtils.hpp> 
♦include <vcl\Controls.hpp> 
♦include <vcl\Classes .hpp> 
♦include <vcl\Forms .hpp> 

// 

class PACKAGE TSecretForm : public TForm 

{ 

__published: // IDE-managed Components 

void __fastcall FormCreate (TObject * Sender ) ; 
private: 

int FSecretCode; // declare a private data member 

public: // User declarations 

__fastcall TSecretForm(TComponent* Owner); 

}; 

// 

extern TSecretForm *SecretForm; 

// 

♦endif 

II file .CPP e il seguente: 

♦include <vcl.h> 
♦pragma hdrstop 
♦include "hidelnfo.h" 

// 

♦pragma package (smart_init ) ; 
♦pragma resource "*.dfm" 
TSecretForm *SecretForm; 

// 

fastcall TSecretForm: :TSecretForm(TComponent* Owner) 

: TForm (Owner) 



Programmazione object-oriented per gli scrittori di componenti 46-5 



Controllo dell'accesso 

{ 
} 

// 

void __fastcall TSecretForm: :FormCreate (TObject *Sender) 

{ 

FSecretCode = 42; // this compiles correctly 

} 

La seconda parte dell'esempio e un'altra unit di scheda che tenta di assegnare un 
valore al membro dati FSecretCode della scheda SecretForm. II file header della unit e il 
seguente: 

♦ifndef TestHideH 
♦define TestHideH 
// 

♦include <vcl\SysUtils.hpp> 
♦include <vcl\Controls.hpp> 
♦include <vcl\Classes .hpp> 
♦include <vcl\Forms .hpp> 

// 

class PACKAGE TTestForm : public TForm 

{ 

__published: // IDE-managed Components 

void __fastcall FormCreate (TObject * Sender ) ; 
public: // User declarations 

fastcall TTestFormfTComponent* Owner); 

}; 

// 

extern TTestForm *TestForm; 

// 

♦endif 

II file .CPP e riportato di seguito. Poiche il gestore di evento OnCreate tenta di 
assegnare un valore al membro dati private della scheda SecretForm, la compilazione 
non va a buon fine e viene visualizzato il messaggio di errore 

'TSecretForm: : FSecretCode' is not accessible. 

♦include <vcl.h> 
♦pragma hdrstop 
♦include "testHide.h" 
♦include "hidelnfo.h" 

// 

♦pragma package(smart_mit) ; 
♦pragma resource "*.dfm" 
TTestForm *TestForm; 

// 

fastcall TTestForm: :TTestForm(TComponent* Owner) 

: TForm (Owner) 

{ 
} 

// 

void __fastcall TTestForm: : FormCreate (TObject *Sender) 

{ 

SecretForm->FSecretCode = 13; //compiler stops here with error message 
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} 

Anche se un programma che usa la unit Hidelnfo puo usare classi di tipo TSecretForm, 
quello stesso programma non puo accedere al membro dati FSecretCode di nessuna di 
quelle classi. 

Nelle applicazioni CLX i nomi e le ubicazioni di alcuni file header sono differenti. Ad 
esempio, <vcl\controls .hpp> is <clx\qcontrols .hpp> in CLX. 

Definizione dell'interfaccia per lo scrittore di componenti 



La dichiarazione di una parte di una classe come protected rende quella parte visibile 
solamente alia stessa classe e ai suoi discendenti. 

Si possono utilizzare le dichiarazioni protected per definire Yinterfaccia dello scrittore 
di componenti alia classe. Le unit dell'applicazione non hanno accesso alle parti 
protette, ma ce l'hanno le classi derivate. Cio significa che chi scrive componenti puo 
modificare il modo in cui opera una classe senza renderne visibili i dettagli a chi 
sviluppa applicazioni. 

Un errore comune e quello di provare ad accedere ai metodi protetti dall'interno di 
un gestore di evento. Di solito i gestori di evento sono metodi della scheda, e non del 
componente che riceve l'evento. Di conseguenza essi non hanno accesso ai metodi 
protetti del componente (a meno che il componente non sia dichiarato nella stessa 
unit della scheda). 

Definizione dell'interfaccia di esecuzione 



Se una parte di una classe viene dichiarata public, quella parte diventa visibile a 
ciascuna riga di codice che ha accesso alia classe. 

Le parti pubbliche sono disponibile in esecuzione a tutto il codice, e pertanto le parti 
pubbliche di una classe definiscono la sua interfaccia di esecuzione. L'interfaccia di 
esecuzione e utile quegli elementi non significativi o inadatti in fase di progettazione, 
come le proprieta dipendenti da dati immessi in esecuzione o che sono a sola lettura. 
Devono essere resi pubblici anche i metodi che possono essere chiamati da chi 
sviluppa applicazioni. 

Di seguito e riportato un esempio che mostra due proprieta a sola lettura dichiarate 
come parte dell'interfaccia di esecuzione di un componente: 

class PACKAGE TSampleComponent : public TComponent 
{ 

private: 

int FTempCelsius ; // implementation details are private 

int GetTempFahrenheit ( ) ; 
public: 

__property int TempCelsius = {read=FTempCelsius} ; // properties are public 
property int TempFahrenheit = {read=GetTempFahrenheit } ; 

}; 

Questo e il metodo GetTempFahrenheit nel file .CPP: 
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int TSampleComponent : :GetTempFahrenheit ( ) 

{ 

return FTempCelsius * (9 / 5) + 32; 

} 

Definizione dell'interfaccia di progettazione 



La dichiarazione di una parte di una classe come published rende quella parte 
pubblica e genera anche informazioni di tipo in esecuzione. Tra l'altro, le 
informazioni di tipo in , esecuzione consentono all' Object Inspector di accedere alle 
proprieta e agli eventi. 

Poiche si possono vedere nell' Object Inspector, le parti pubblicate di una classe 
definiscono Vinterfaccia di progettazione di quella classe. L'interfaccia di progettazione 
dovrebbe includere qualsiasi aspetto della classe che uno sviluppatore di 
applicazioni potrebbe voler personalizzare in fase di sviluppo, ma deve escludere 
qualsiasi proprieta dipendente da informazioni specifiche legate all'ambiente di 
esecuzione. 

Le proprieta a sola lettura non possono essere parte dell'interfaccia di progettazione 
dato che chi sviluppa applicazioni non puo assegnare loro dei valori. Le proprieta a 
sola lettura dovrebbero essere percio public, invece che published. 

Di seguito e riportato un esempio di una proprieta published di nome Temperature. 
Siccome e published, in fase di progettazione viene mostrata nell' Object Inspector. 

class PACKAGE TSampleComponent : public TComponent 

{ 

private: 

int FTemperature; 

__published: 

__property int Temperature = {read=FTemperature, write=FTemperature} ; 

}; 



Dispatch dei metodi 



Dispatch e il termine usato per descrivere in che modo l'applicazione determina quali 
sono i metodi della classe che devono essere chiamati quando incontra una chiamata 
a un metodo della classe. Quando si scrive del codice che chiama un metodo della 
classe, la chiamata e simile ad una qualsiasi altra chiamata a funzione. Le classi, 
tuttavia, hanno due modi differenti di eseguire il dispatch dei metodi. 

I due tipi di dispatch dei metodi si differenziano a seconda che siano per 

• Metodi regolari (non virtuali) 

• Metodi virtuali 
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Dispatch dei metodi 



I metodi di classe sono regolari (o non virtuali) a meno che non vengano dichiarati 
esplicitamente come virtuali, oppure a patto che essi ridefiniscano un metodo 
virtuale presente in una classe base. II compilatore e in grado di determinare 
l'indirizzo esatto di un membro di una classe regolare in fase di compilazione. 
Questa funzionalita e nota come "binding in compilazione". 

Un metodo regolare di una classe base viene ereditato dalle classi derivate. 
Nell'esempio seguente, un oggetto di tipo Derived puo chiamare il metodo RegularO 
come se fosse un proprio metodo. La dichiarazione di un metodo in una classe 
derivata con lo stesso nome e gli stessi parametri di metodo regolare nella classe 
antenato sostituisce il metodo dell'antenato. Nell'esempio seguente, quando si 
chiama il metodo d->AnotherRegular(), esso viene smistato al metodo sostitutivo di 
AnotherRegularO della classe Derived. 

class Base 

{ 

public: 

void RegularO ; 

void AnotherRegularO ; 

virtual void Virtual 0; 

}; 

class Derived : public Base 

{ 

public: 

void AnotherRegularO ; 
void Virtual ( ) ; 

}; 

void FunctionOne ( ) 

{ 

Derived *d; 
d = new Derived; 
d->Regular() ; 

d->AnotherRegular ( ) ; 

delete d; 

} 

void FunctionTwo (Base *b) 

{ 

b->Virtual() ; 
b->AnotherRegular ( ) ; 

} 

Metodi virtuali 



A differenza dei metodi regolari, che vengono collegati in fase di compilazione, i 
metodi virtuali vengono collegati in esecuzione. II meccanismo virtuale di C++ 
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// replaces Base: : AnotherRegularO 
// overrides Base: :Virtual ( ) 



// Calling Regular!) as it were a member of Derived 

// The same as calling d->Base: :Regular() 

// Calling the redefined AnotherRegularO, ... 

// ... the replacement for Base: : AnotherRegularO 



Membri astratti d i classi 

consente di chiamare un metodo in base al tipo della classe che si sta utilizzando per 
chiamare il metodo. 

Nell'esempio precedente, se si chiamasse la funzione FunctionTwoO con un puntatore 
a un oggetto di Derived, verrebbe chiamata la funzione Derived::Virtual(). II 
meccanismo virtuale ispeziona dinamicamente in esecuzione il tipo della classe 
dell'oggetto che le viene passato e la smista al metodo opportune Ma la chiamata 
alia funzione regolare b->AnotherRegular() chiamera sempre Base::AnotherRegular() in 
quanto l'indirizzo di AnotherRegularO e stato determinato in fase di compilazione. 

Per dichiarare un nuovo metodo virtuale, anteporre alia dichiarazione del metodo la 
parola chiave virtual. 

Quando il compilatore incontra la parola chiave virtual, crea un elemento nella 
tabella dei metodi virtuali della classe (VMT). La VMT conserva gli indirizzi di tutti i 
metodi virtuali presenti in una classe. Questa tabella di consultazione viene utilizzata 
in fase esecuzione per determinare che b->Virtual deve chiamare Derived: :Virtual() 
invece di Base::Virtual(). 

Quando si deriva una nuova classe da una classe preesistente, la nuova classe riceve 
una propria VMT, che comprende gli elementi della VMT dell'antenato a cui 
vengono aggiunti tutti i metodi virtuali dichiarati nella nuova classe. Inoltre, la classe 
derivata puo ridefinire tutti i metodi virtuali ereditati. 

Ridefinizione dei metodi 

Ridefinire i metodi significa estendere o perfezionare un metodo di un antenato, 
invece che sostituirlo. Per ridefinire un metodo in una classe discendente, dichiarare 
di nuovo il metodo nella classe derivata, assicurandosi che il numero e il tipo degli 
argomenti siano gli stessi. 

II codice successivo mostra la dichiarazione di due semplici componenti. II primo 
dichiara due metodi, ciascuno con un differente tipo di dispatch. L'altro, derivato dal 
primo, sostituisce il metodo non virtuale e ridefinisce il metodo virtuale. 

class PACKAGE TFirstComponent : public TComponent 

{ 

public: 

void Moved; // regular method 

virtual void Flash (); // virtual method 

}; 

class PACKAGE TSecondComponent : public TFirstComponent 
{ 

public: 

void Moved; // declares new method "hiding" TFirstComponent : :Move ( ) 

void Flash (); // overrides virtual TFirstComponent :: Flash in TFirstComponent 

}; 

Membri astratti di classi 



Quando un metodo e dichiarato come abstract in una classe antenato, occorre 
renderlo evidente (dichiarandolo o implementandolo di nuovo) in qualsiasi 
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componente discendente prima di poter utilizzare nelle applicazioni il nuovo 
componente. C++Builder non e in grado di creare istanze di una classe che contiene 
membri astratti. Per maggiori informazioni sul modo di rendere evidenti le parti 
ereditate delle classi, consultare il Capitolo 47, "Creazione di proprieta", and 
Capitolo 49, "Creazione di metodi". 

Classi e puntatori 



Ogni classe (e percio ogni componente) e in realta un pimtatore. II fatto che la classe 
sia un puntatore diventa importante quando una classe viene passata come 
parametro. Come regola generale, si dovrebbero passare le classi per valore invece 
che per riferimento. II motivo e che le classi sono gia dei puntatori, e come tali sono 
riferimenti; passando una classe per riferimento equivale a passare un riferimento a 
un riferimento. 
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Capitolo 




Creazione 



di proprieta 



Le parti piu evidenti dei componenti sono le proprieta. Chi sviluppa applicazioni 
puo visualizzarle e manipolarle in fase di progettazione e avere un'immediata 
risposta di come il componente reagisce nel modulo di impostazione schede. Le 
proprieta ben progettate agevolano l'impiego del componente da parte di altri e ne 
assicurano una piu facile manutenzione. 

Per fare il miglior uso possibile delle proprieta dei componenti e necessario 
analizzare alcuni aspetti: 

• Perche creare le proprieta 

• Tipi di proprieta 

• Pubblicazione di proprieta ereditate 

• Definizione delle proprieta 

• Creazione di proprieta array 

• Registrazione e caricamento delle proprieta 



Dal punto di vista dello sviluppatore di applicazioni, le proprieta appaiono come 
variabili. Gli sviluppatori possono impostarle o leggerne i valori come se fossero 
membri dati. (L'unica cosa che non si puo fare con una proprieta, ma solo con una 
variabile, e passarla per riferimento a un metodo sotto forma di argomento.) 

Le proprieta sono molto piu potenti dei semplici membri dati perche 

• Gli sviluppatori di applicazioni possono impostare le proprieta durante la 
progettazione. Mentre i metodi sono disponibili solo in fase di esecuzione, le 
proprieta consentono invece alio sviluppatore di personalizzare i componenti 
prima di eseguire l'applicazione. Le proprieta possono essere mostrate nell'Object 
Inspector, che semplifica il lavoro del programmatore: invece di gestire svariati 
parametri per costruire un oggetto, si lascera a C++Builder il compito di leggerne i 
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valori dall'Object Inspector. L'Object Inspector convalida inoltre le assegnazioni 
delle proprieta non appena vengono eseguite. 

• Le proprieta possono mascherare dettagli di implementazione. Ad esempio, i dati 
memorizzati internamente in formato crittografato possono apparire non 
crittografati come valori di una proprieta; anche se il valore e un semplice numero, 
il componente puo cercare il valore in un database o eseguire calcoli complessi per 
determinarlo. Le proprieta consentono di aggiungere effetti complessi ad 
assegnazioni a prima vista semplici; cio che appare un'assegnazione a un membro 
dati puo essere invece una chiamata a un metodo che implica un'elaborazione 
complessa. 

• Le proprieta possono essere virtuali. Quindi, cio che a uno sviluppatore di 
applicazioni appare come una proprieta singola puo essere invece implementato 
in modo diverso in componenti differenti. 

Un semplice esempio e la proprieta Top di tutti i controlli.L'assegnazione di un 
nuovo valore a Top non solo modifica un valore memorizzato, ma riposiziona ed 
aggiorna il controllo. E gli effetti dell'impostazione di una proprieta non sono 
necessariamente limitati a un singolo componente. Per esempio, l'impostazione a 
true della proprieta Down di uno SpeedButton provoca l'impostazione a false di tutti 
gli altri pulsanti appartenenti alio stesso gruppo. 



Tipi di proprieta 



Una proprieta puo essere di un qualunque tipo. Tipi diversi sono visualizzati in 
modo differente nell'Object Inspector, che, in fase di progetto, convalida le 
assegnazioni di proprieta non appena vengono create. 

Tabella 47.1 Come appaiono le proprieta nell'Object Inspector 



Semplice Le proprieta numeriche, di tipo carattere e stringa appaiono nell'Object 

Inspector rispettivamente come numeri, caratteri e stringhe. L'utente puo 
scrivere e modificare direttamente il valore della proprieta. 

Enumerato Le proprieta dei tipi enumerati (compreso Boolean) appaiono come stringhe di 

testo modificabili. L'utente puo far scorrere tutti i possibili valori facendo 
doppio clic nella colonna del valore. Appare anche un elenco a discesa che 
mostra tutti i valori possibili del tipo enumerato. 

Set Le proprieta dei tipi set appaiono nell'Object Inspector come un insieme. 

Espandendo l'insieme con un doppio clic del mouse, l'utente puo trattare ogni 
elemento del set come un valore booleano: true se l'elemento e incluso nel set, 
false se non lo e). 

Oggetto Le proprieta che sono a loro volta classi spesso dispongono di propri editor, 

specificati nella procedura di registrazione del componente. Tuttavia, se la 
classe che fa capo a una proprieta contiene a sua volta la proprieta Published, 
l'Object Inspector permette all'utente di espandere l'elenco (con un doppio 
clic) per includere quelle proprieta e di modificarle individualmente. Le 
proprieta dell'oggetto devono discendere da TPersistent. 
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Tabella 47.1 Come appaiono le proprieta nell'Object Inspector (continua) (continua) 
Tipo di proprieta Trattamento dell' Object Inspector 

Interface Le proprieta che sono interfacce possono essere visualizzate nell'Object 

Inspector purche il valore sia un'interfaccia che e implementata da un 
componente (un discendente di TComponent). Le proprieta interfaccia hanno 
spesso i propri editor di proprieta. 

Array Le proprieta array devono avere i propri editor; V Object Inspector non ha il 

supporto interno per la modifica delle proprieta array. E possibile specificare 
un editor di proprieta quando si registra il componente. 



Pubblicazione di proprieta ereditate 



Tutti i componenti ereditano proprieta dalle proprie classi antenate. Quando si 
deriva un componente da uno esistente, il nuovo componente eredita tutte le 
proprieta del suo antenato immediato. Se si deriva il componente da una classe 
astratta, la maggior parte delle proprieta ereditate sono protected (protette) o public 
(pubbliche) ma non sono published (rese pubbliche. 

Per rendere disponibile in fase di progettazione nell'Object Inspector una proprieta 
protetta o pubblica bisogna ridichiararla come published. Ridichiarare significa 
aggiungere una dichiarazione per la proprieta ereditata alia dichiarazione della 
classe discendente. 

Se si deriva un componente VCL da TWinControl, per esempio, esso eredita anche la 
proprieta DockSite protetta. Ridichiarando invece DockSite nel nuovo componente e 
possibile cambiare il livello di protezione e trasformarlo in public o published. 

II codice che segue mostra come ridichiarare DockSite in modo published rendendolo 
disponibile durante lo sviluppo. 

class PACKAGE TSampleComponent : public TWinControl 
{ 

__published: 

__property DockSite; 

}; 

Nel ridichiarare una proprieta si specifica solo il nome della proprieta, non il tipo e le 
altre informazioni descritte nel paragrafo successivo "Definizione delle proprieta". Si 
possono anche dichiarare nuovi valori predefiniti e specificare se memorizzare la 
proprieta. 

La ridichiarazione pud diminuire la protezione di una proprieta, ma non aumentarla. 
Pertanto, e possibile rendere pubblica una proprieta protetta, ma non e consentito 
nascondere una proprieta pubblica ridichiarandola come protetta. 

Definizione delle proprieta 



Questa sezione illustra come dichiarare nuove proprieta e spiega alcune convenzioni 
seguite per i componenti standard. Gli argomenti trattati sono i seguenti: 
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• Dichiarazione della proprieta 

• Memorizzazione interna dei dati 

• Accesso diretto 

• Access methods 

• Valori predefiniti delle proprieta 

Dichiarazione della proprieta 



AUna proprieta e dichiarata nella dichiarazione della classe del componente. Per 
dichiarare una proprieta, occorre specificare tre cose: 

• II nome della proprieta. 

• II tipo della proprieta. 

• I metodi usati per leggere e scrivere il valore della proprieta. Se non viene 
dichiarato il metodo di scrittura, la proprieta e a sola lettura. 

Le proprieta dichiarate in una sezione published della dichiarazione della classe 

del componente sono modificabili in fase di progetto con Object Inspector. II valore 
di una proprieta resa pubblica viene salvato assieme al componente nel file della 
scheda. Le proprieta dichiarate in una sezione public sono disponibili in fase di 
esecuzione e possono essere lette o impostate da programma. 

Di seguito e riportata una tipica dichiarazione di proprieta di nome Count. 

class PACKAGE TYourComponent : public TComponent 
{ 

private: 

int FCount; // data member for storage 

int __fastcall GetCountO; // read method 

void __fastcall SetCount( int ACount ); // write method 

public: 

__property int Count = {read=GetCount, write=SetCount} ; // property declaration 

};" 

Memorizzazione interna dei dati 



Non vi sono restrizioni su come memorizzare il dato di una proprieta. In generale, 
comunque, i componenti di C++Builder seguono queste convenzioni: 

• I dati delle proprieta vengono memorizzati all'interno dei membri dati della 
classe. 

• I membri dati utilizzati per memorizzare i dati della proprieta sono privati e 
dovrebbero essere accessibili soltanto dall'intemo del componente stesso. I 
componenti derivati dovrebbero utilizzare la proprieta ereditata: non hanno 
bisogno di accedere direttamente all'area di memorizzazione interna dei dati della 
proprieta. 
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• I nomi degli identificatori di questi membri dati iniziano con la lettera F seguita 
dal nome della proprieta. Per esempio, i dati della proprieta Width definita in 
TControl sono memorizzati in un membro dati di nome FWidth. 

II principio che e alia base di queste convenzioni e che solo i metodi di 
implementazione di una proprieta dovrebbero avere accesso ai dati cui essa si 
riferisce. Se un metodo o un'altra proprieta ha bisogno di cambiare quel dato, 
dovrebbe farlo utilizzando la proprieta e non accedendo direttamente ai dati 
memorizzati. Cio garantisce che l'implementazione di una proprieta puo cambiare 
senza invalidare i componenti derivati. 

Accesso diretto 



L'accesso diretto e la maniera piu semplice per rendere disponibili i dati delle 
proprieta. Cio significa che le sezioni read e write della dichiarazione della proprieta 
specificano che l'assegnazione o la lettura del valore della proprieta accedono 
direttamente al membro dati di memorizzazione interna senza chiamare un metodo 
di accesso. L'accesso diretto e utile se si vuole rendere disponibile una proprieta 
nell'Object Inspector ma si vuole evitare che le modifiche al valore provochino 
un'elaborazione immediata. 

E abbastanza comune avere accesso diretto per la sezione read di una dichiarazione 
di proprieta ma usare un metodo di accesso per la sezione write. Cio fa si che lo stato 
del componente venga aggiornato quando il valore della proprieta cambia. 

La dichiarazione di un tipo componente riportata di seguito mostra una proprieta 
che utilizza l'accesso diretto sia per la parte read sia per la parte write. 

class PACKAGE TSampleComponent : public TComponent 

{ 

private: // internal storage is private 

bool FReadOnly; // declare data member to hold value 

__published: // make property available at design time 

__property bool Readonly = {read=FReadOnly, write=FReadOnly} ; 

}; 

Access methods 



Nelle parti read e write di una dichiarazione di proprieta si puo specificare, anziche 
un membro dati, un metodo di accesso. I metodi di accesso devono essere protetti e 
di solito sono dichiarati come virtual; cio permette al componente discendente di 
ridefinire l'implementazione della proprieta. 

Bisogna evitare di rendere pubblici i metodi di accesso. Tenerli protetti assicura che 
lo sviluppatore di applicazioni non modifichi inavvertitamente una proprieta 
chiamando un metodo. 

Di seguito e riportata una classe che dichiara tre proprieta utilizzando lo specificatore 
index, il che consente alle tre proprieta di utilizzare gli stessi metodi di accesso in 
lettura e scrittura: 
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class PACKAGE TSampleCalendar : public TCustomGrid 

{ 

private: 

int fastcall GetDateElement (int Index); // note Index parameter 

void fastcall SetDateElement (int Index, int Value); 

public: 

__property int Day = {read=GetDateElement , write=SetDateElement, index=3, nodefault}; 

property int Month = {read=GetDateElement , write=SetDateElement , index=2, nodefault}; 

property int Year = {read=GetDateElement , write=SetDateElement, index=l, nodefault}; 

}; 

Poiche ogni elemento della data (giorno, mese e anno) e un intero e poiche 
l'impostazione di ciascuno di essi richiede la codifica della data, il codice evita la 
duplicazione condividendo i metodi di lettura e scrittura di tutte e tre le proprieta. 
Occorre quindi solo un metodo per leggere un elemento della data e un altro metodo 
per scriverlo. 

Di seguito e riportato il metodo di lettura per ottenere un elemento della data: 

int fastcall TSampleCalendar: :GetDateElement (int Index) 

{ 

unsigned short AYear, AMonth, ADay; 
int result; 

FDate.DecodeDate(&AYear, &AMonth, &Aday) ; // break date into elements 

switch (Index) 

{ 

case 1: result = AYear; break; 
case 2: result = AMonth; break; 
case 3: result = ADay; break; 
default: result = -1; 

} 

return result; 

} 

Questo e il metodo di scrittura usato per impostare l'opportuno elemento della data: 

void fastcall TSampleCalendar: : SetDateElement (int Index, int Value) 

{ 

unsigned short AYear, AMonth, ADay; 

if (Value > 0) // all elements must be positive 

{ 

FDate.DecodeDate(&AYear, SAMonth, &ADay) ; // get date elements 

switch (Index) 

{ 

case 1: AYear = Value; break; 
case 2: AMonth = Value; break; 
case 3: ADay = Value; break; 
default: return; 

} 

} 

FDate = TDateTime (AYear, AMonth, ADay); // encode the modified date 
Refresh));// update the visible calendar 

} 
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II metodo read 

II metodo read per una proprieta e una funzione che non richiede parametri (tranne 
nei casi citati di seguito) e restituisce un valore dello stesso tipo della proprieta. Per 
convenzione il nome della funzione e Get seguito dal nome della proprieta. Per 
esempio, il metodo read relativo a una proprieta di nome Count sara GetCount. II 
metodo read manipola i dati memorizzati internamente in modo da produrre il 
valore della proprieta con il tipo appropriato. 

Le uniche eccezioni alia regola che impone l'assenza di parametri sono le proprieta 
array e quelle che utilizzano specificatori di indice (vedere il paragrafo "Creazione di 
proprieta array" a pagina 47-8), in quanto entrambe passano i propri valori di indice 
come parametri. (Per creare un singolo metodo read condiviso da piu proprieta, 
usare gli specificatori di indice.) 

ISe non si dichiara un metodo read, la proprieta e a sola scrittura. Le proprieta a sola 
scrittura sono utilizzate raramente. 

II metodo write 

II metodo write per una proprieta e una funzione membro che richiede un solo 
parametro dello stesso tipo della proprieta (tranne nei casi citati di seguito). II 
parametro puo essere passato per riferimento o per valore e pud avere un nome 
qualsiasi. Per convenzione, il nome del metodo write e Set seguito dal nome della 
proprieta. Ad esempio, il metodo write di una proprieta chiamata Count sara 
SetCount. II valore passato nei parametro diventa il nuovo valore della proprieta; il 
metodo write deve compiere tutte le operazioni necessarie per collocare il dato 
appropriato nell'area di memorizzazione interna della proprieta. 

Le uniche eccezioni alia regola del singolo parametro sono le proprieta array e quelle 
che utilizzano specificatori di indice, in quanto passano i propri valori di indice come 
secondo parametro. (Per creare un singolo metodo write condiviso da piu proprieta, 
usare gli specificatori di indice.) 

Se non si dichiara un metodo write, la proprieta e a sola lettura. 

I metodi write di solito verificano se un nuovo valore differisce dal valore attuale 
prima di modificare la proprieta. Per esempio, di seguito e riportato un semplice 
metodo write per una proprieta di tipo intero di nome Count che memorizza il suo 
valore attuale in un membro dati di nome FCount. 

void __fastcall TMyComponent :: SetCount ( int Value ) 
{ 

if ( Value != FCount ) 

{ 

FCount = Value; 
Updated ; 

} 

Valori predefiniti delle proprieta 



Quando si dichiara una proprieta, e possibile specificare un valore predefinito. 
C++Builder utilizza il valore predefinito per determinare se memorizzare la 
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proprieta in un file di scheda. Se non si specifica un valore predefinito per una 
proprieta, C++Builder memorizza sempre la proprieta. 

Per dichiarare un valore predefinito per una proprieta, aggiungere un segno di 
uguale dopo il nome della proprieta e impostare una coppia di parentesi graffe in cui 
includere la parola chiave default seguita dal valore predefinito. Ad esempio: 

__property bool IsTrue = {default=true} ; 

La dichiarazione di un valore predefinito non imposta la proprieta a quel valore. II 
metodo costruttore del componente deve inizializzare i valori della proprieta quando 
e necessario. Comunque, poiche gli oggetti inizializzano sempre i propri membri dati 
a 0, non e strettamente necessario che il costruttore imposti le proprieta di tipo 
integer a 0, quelle di tipo stringa a null o quelle booleane a false. 

Specifica di una proprieta senza valore predefinito 

Quando una proprieta viene ridichiarata, e possibile specificare che non ha un valore 
predefinito, anche se la proprieta ereditata ne specificava uno. 

Per designare una proprieta che non ha un valore predefinito, aggiungere un segno 
di uguale dopo il nome della proprieta e impostare una coppia di parentesi graffe in 
cui includere la parola chiave nodef ault. Ad esempio: 

__property int Newlnteger = {nodef ault } ; 

Quando si dichiara una proprieta per la prima volta, non e necessario includere 
nodef ault. L'assenza di un valore dichiarato predefinito significa che non c'e un 
valore predefinito. 

Di seguito viene riportata la dichiarazione di un componente che include una singola 
proprieta booleana di nome IsTrue con un valore predefinito pari a true, e il 
costruttore che imposta il valore predefinito. 

class PACKAGE TSampleComponent : public TComponent 

{ 

private: 

bool FIsTrue; 
public: 

virtual __fastcall TSampleComponent! TComponent* Owner ) ; 
__published: 

__property bool IsTrue = {read=FIsTrue, write=FIsTrue, default=true} ; 

}; 

__fastcall TSampleComponent: : TSampleComponent ( TComponent* Owner ) 
: TComponent ( Owner ) 

{ 

FIsTrue = true; 

} 

Creazione di proprieta array 



Alcune proprieta si prestano a essere indicizzate come gli array. Per esempio, la 
proprieta Lines di TMemo e un elenco indicizzato delle stringhe che costituiscono il 
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testo del memo; si puo trattarlo come un array di stringhe. Lines consente di accedere 
in modo naturale a un particolare elemento (una stringa) in una serie di dati piu 
estesa (il testo del memo). 

Le proprieta array vengono dichiarate come le altre proprieta, a meno che 

• La dichiarazione comprenda uno o piu indici che hanno un tipo specificato. Gli 
indici possono essere di qualsiasi tipo. 

• Le parti read e write della dichiarazione di proprieta, se specificate, devono essere 
dei metodi. Non possono essere membri dati. 

I metodi read e write per una proprieta array accettano parametri aggiuntivi che 
corrispondono agli indici. I parametri devono essere nello stesso ordine e dello stesso 
tipo degli indici specificati nella dichiarazione. 

Ci sono alcune differenze importanti tra le proprieta array e gli array. A differenza 
dell'indice di un array, l'indice di una proprieta array non deve essere di tipo integer. 
Si puo indicizzare una proprieta su una stringa, per esempio. Inoltre, si puo far 
riferimento solo ai singoli elementi di una proprieta array e non all'intero intervallo 
della proprieta. 

L'esempio seguente mostra la dichiarazione di una proprieta che restituisce una 
stringa basata su un indice integer. 

class PACKAGE TDemoComponent : public TComponent 

{ 

private: 

System: :AnsiString __fastcall GetNumberSize(int Index); 
public: 

__property System: :AnsiString NumberSize [int Index] = {read=GetNumberSize} ; 

}; 

Questo e il metodo GetNumberSize nel file .CPP: 

System: :AnsiString fastcall TDemoComponent : :GetNumberSize (int Index) 

{ 

System: :AnsiString Result; 

switch (Index) 

{ 

case 0: 

Result = "Zero"; 

break; 
case 100: 

Result = "Medium" ; 

break; 
case 1000: 

Result = "Large"; 

break; 

default: Result = "Unknown size"; 

} 

return Result; 

} 
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Creazione di proprieta per i sottocomponenti 



Per impostazione predefinita, quando il valore di una proprieta e un altro 
componente, si assegna un valore a quella proprieta aggiungendo alia scheda o al 
modulo dati un'istanza dell'altro componente e quindi assegnando quel componente 
come valore della proprieta. Tuttavia, e anche possibile che il componente crei la 
propria istanza dell'oggetto che implementa il valore della proprieta. Un tale 
componente dedicato viene detto sottocomponente. 

Tutti gli oggetto persistenti (tutti i discendenti di TPersistent) possono essere 
sottocomponenti. A differenza dei singoli componenti che, talvolta, possono essere 
assegnati come valore di una proprieta, le proprieta pubblicate dei sottocomponenti 
vengono salvate con il componente che li crea. Affinche cio sia vero, comunque, 
devono essere soddisfatte le seguenti condizioni: 

• L 'Owner del sottocomponente deve essere il componente che lo crea e lo utilizza 
come valore di una proprieta pubblicata. Nel caso di sottocomponenti che 
discendono da TComponent, e possibile fare cio impostando la proprieta Owner del 
sottocomponente. Per altri sottocomponenti, e necessario ridefinire il metodo 
GetOwner dell'oggetto persistente in modo che restituisca il componente che sta 
creando. 

• Se il sottocomponente e un discendente di TComponent, deve indicare di essere un 
sottocomponente chiamando il metodo Set Subcomponent. Di solito, questa 
chiamata viene effettuata o dal possessore al momento della creazione del 
sottocomponente oppure dal costruttore del sottocomponente. 

Di solito, le proprieta i cui valori sono sottocomponenti sono a sola lettura. Se si 
permette di modificare una proprieta il cui valore e un sottocomponente, il setter 
della proprieta deve liberare il sottocomponente nel momento in cui al valore della 
proprieta viene assegnato un altro componente. Inoltre, il componente spesso crea 
una nuova istanza del proprio sottocomponente quando la proprieta viene impostata 
a NULL. In caso contrario, se la proprieta fosse stata modificata in un altro 
componente, il sottocomponente non potrebbe essere mai ripristinato in fase di 
progettazione. II seguente esempio illustra un setter di proprieta per una proprieta il 
cui valore e un TTimer: 

void __fastcall TDemoComponent : : SetTimerProp (ExtCtrls : : TTimer *Value) 

{ 

if (Value != FTimer) 
{ 

if (Value) 
{ 

if (FTimer && FTimer->Owner == this) 

delete FTimer; 
FTimer = Value; 

FTimer->FreeNotification (this) ; 

} 

else // NULL value 
{ 

if (FTimer && FTimer->Owner != this) 
{ 
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FTimer = new ExtCtrls : :TTimer (this ) ; 
FTimer.SetSubComponent (true) ; 
FTimer->FreeNotif ication (this ) ; 

} 




Si noti che il setter della proprieta visto in precedenza ha effettuato una chiamata al 
metodo FreeNotification del componente che e stato impostato come valore della 
proprieta. Questa chiamata garantisce che il componente che e stato assegnato come 
valore della proprieta invii una notifica nel caso debba essere distrutto. La notifica 
viene inviata chiamando il metodo Notification. Questa chiamata viene gestita 
ridefinendo il metodo Notification nel seguente modo: 

void fastcall TDemoComponent : Notification (Classes : :TComponent *AComponent, 

Classes : :TOperation Operation) 

{ 

TComponent : :Hotif ication (AComponent , Operation); { call inherited method } 
if ((Operation == opRemove) && (AComponent == (TComponent *)FTimer)) 
FTimer = NULL; 

} 

Registrazione e caricamento delle proprieta 



C++Builder registra le schede e i loro componenti in file scheda (.dfm nella VCL and 
.xfm nella CLX). Un file scheda contiene le proprieta di una scheda e dei suoi 
componenti. Gli sviluppatori in C++Builder aggiungono nelle loro schede 
componenti scritti da altri; tali componenti devono avere la capacita di scrivere le 
loro proprieta nel file scheda quando vengono salvati. Analogamente, quando 
vengono caricati in C++Builder o vengono eseguiti come parte di un'applicazione, i 
componenti devono essere in grado di ripristinarsi automaticamente leggendo le 
proprie proprieta dal file scheda. 

Generalmente non occorre fare nulla perche i componenti siano in grado di lavorare 
con i file scheda, in quanto la capacita di registrare e di ricaricare una 
rappresentazione fa parte del comportamento che essi hanno ereditato. Talvolta, 
comunque, puo essere necessario modificare il modo in cui un componente si 
registra o il modo in cui si inizializza quando viene caricato; pertanto, e importante 
conoscere i meccanismi sottostanti. 

Questi sono gli aspetti della registrazione delle proprieta che occorre conoscere: 

• Uso del meccanismo di registrazione e di caricamento 

• Specifica di valori predefiniti 

• Determinazione di che cosa registrare 

• Inizializzazione dopo il caricamento 

• Registrazione e caricamento di proprieta non pubbliche 
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Uso del meccanismo di registrazione e di caricamento 



La descrizione di una scheda e costituita dall'elenco delle sue proprieta e da 
descrizioni analoghe per ogni suo componente. Ogni componente, compresa la 
scheda stessa, e responsabile della registrazione e del caricamento della propria 
descrizione. 

Per impostazione predefinita, quando un componente si registra, scrive i valori di 
tutte le sue proprieta published che differiscono dai valori predefiniti nell'ordine in 
cui sono state dichiarati. Quando un componente si carica automaticamente, come 
prima operazione si ricostruisce, impostando tutte le proprieta al loro valore 
predefinito, dopo di che legge i valori non predefiniti delle proprieta registrate. 

Questo meccanismo predefinito viene utilizzato da molti componenti, e non richiede 
alcuna azione da parte dello scrittore di componenti. Ci sono, comunque, diversi 
metodi per personalizzare i processi di registrazione e di caricamento in modo da 
adattarli alle esigenze degli specif ici componenti. 

Specifica di valori predefiniti 



I componenti C++Builder salvano i valori delle loro proprieta solo se differiscono da 
quelli predefiniti. C++Builder, se non si specifica diversamente, considera sempre 
una proprieta senza valore predefinito, il che comporta che il componente debba 
registrarla sempre, qualunque sia il suo valore. 

Per specificare un valore predefinito per una proprieta: 

1 Aggiungere un segno di uguale (=) dopo il nome della proprieta. 

2 Dopo il segno di uguale, aggiungere una coppia di parentesi graffe ({ }). 

3 All'interno delle graffe, scrivere la parola chiave default seguita da un altro segno 
di uguale. 

4 Specificare il nuovo valore predefinito. 
Ad esempio: 

property Alignment = {default=taCenter} ; 

E possibile specificare un valore predefinito anche quando si dichiara una proprieta. 
Infatti, una ragione per ridichiarare una proprieta e quella di indicare un valore 
predefinito diverso. 

La specifica del valore predefinito di una proprieta non assegna automaticamente 
quel valore alia proprieta in fase di creazione di un oggetto. Occorre assicurarsi che il 
costruttore del componente assegni il valore necessario. Una proprieta, il cui valore 
non e impostato dal costruttore, assume come valore zero, cioe, qualunque valore 
assunto dalla proprieta quando l'area di memorizzazione viene impostata a 0. In altre 
parole, i valori numerici hanno come impostazione predefinita 0, i valori booleani 
sono false, i puntatori sono NULL, e cosi via. In caso di dubbio, assegnare un valore 
nel costruttore del metodo. 
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II codice seguente mostra la dichiarazione di un componente che specifica un valore 
predefinito per la proprieta Align e rimplementazione da parte del costruttore del 
componente che imposta il valore predefinito. In questo caso, il nuovo componente e 
un caso speciale di un componente panel standard che sara utilizzato per le barre di 
stato di una finestra, in modo che l'allineamento predefinito sia il fondo dell'oggetto 
proprietario. 

class PACKAGE TMyStatusBar : public TPanel 
{ 

public: 

virtual __fastcall TMyStatusBar (TComponent* AOwner); 
__published: 
__property Align = {default=alBottom} ; 

}; 

II costruttore del componente TMyStatusBar nel file .CPP e il seguente: 

__fastcall TMyStatusBar: : TMyStatusBar (TComponent* AOwner) 
: TPanel (AOwner) 

{ 

Align = alBottom; 



E possibile controllare se C++Builder registra tutte le proprieta dei componenti. 
Come impostazione predefinita, tutte le proprieta presenti nella parte published 
della dichiarazione di classe vengono registrate. Si puo scegliere di non registrare 
una determinata proprieta, oppure si puo designare una funzione che determini se 
registrare o meno una proprieta. 

Per controllare se C++Builder debba registrare o meno una proprieta: 

1 Aggiungere un segno di uguale (=) dopo il nome della proprieta. 

2 Dopo il segno di uguale, aggiungere una coppia di parentesi graffe({}). 

3 All'interno delle graffe, scrivere la parola chiave stored seguita da true, false o dal 
nome di un metodo booleano. 

II codice seguente mostra un componente che dichiara tre nuove proprieta. Una 
viene registrata sempre, una non viene mai registrata, mentre la terza viene registrata 
a seconda del valore di una funzione booleana: 

class PACKAGE TSampleComponent : public TComponent 

{ 

protected : 

bool __fastcall StoreltO; 
public : 



Determinazione di che cosa registrare 



.published : 



__property int Important = 

property int Unimportant 

__property int Sometimes = 



{stored=true} ; 
= {stored=false}; 

{stored=Store!t} ; 



// always stored 
// never stored 

// storage depends on function value 



}; 
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Inizializzazione dopo il caricamento 



Un componente, dopo aver letto tutti i valori delle sue proprieta dalla sua descrizione 
registrata, richiama un metodo virtuale chiamato Loaded, che esegue tutte le 
inizializzazioni richieste. La chiamata di Loaded avviene prima che compaiano la 
scheda e i suoi controlli, cosi che non c'e da preoccuparsi del fatto che 
l'inizializzazione possa provocare sfarfallio sullo schermo. 

Per inizializzare un componente dopo che ha caricato i valori delle sue proprieta, 
occorre ridefinire il metodo Loaded. 

La prima cosa da fare in un metodo Loaded e chiamare il metodo ereditato Loaded. Cio 
assicura che tutte le proprieta ereditate verranno inizializzate correttamente prima 
che sia inizializzato il componente. 

Registrazione e caricamento di proprieta non pubbliche 



Per impostazione predefinita, sole le proprieta pubbliche vengono caricate e salvate 
con un componente. Tuttavia, e possibile caricare e salvare anche proprieta non 
pubbliche. Questa possibilita consente di avere proprieta persistenti che non 
appaiono nell'Object Inspector. Cio consente anche ai componenti di memorizzare e 
caricare valori di proprieta che C++Builder non e in grado di leggere o di scrivere 
perche il valore della proprieta e troppo complesso. Per esempio, l'oggetto TStrings 
non puo appoggiarsi al comportamento automatico di C++Builder per memorizzare 
e caricare le stringhe che esso rappresenta e deve utilizzare il meccanismo spiegato di 
seguito. 

E possibile salvare le proprieta non pubbliche aggiungendo del codice che spiega a 
C++Builder come caricare e salvare il valore delle proprieta. 

Per scrivere il codice necessario a caricare e salvare le proprieta, seguire le istruzioni 
seguenti: 

1 Creare dei metodi per memorizzare e caricare il valore della proprieta. 

2 Ridefinire il metodo DefineF 'roper ties, passando quei metodi un oggetto filer. 

Creazione di metodi per memorizzare e caricare i valori delle proprieta 

Per memorizzare e caricare le proprieta non pubbliche, per prima cosa si deve creare 
un metodo per memorizzare il valore della proprieta e un altro metodo per caricarlo. 
Esistono due possibilita: 

• Creare un metodo di tipo TWriterProc per memorizzare il valore della proprieta e 
un metodo di tipo TReaderProc per caricare il valore della proprieta. Questo 
approccio consente di sfruttare le capacita intrinseche di C++Builder di 
salvataggio e caricamento di tipi semplici. Se il valore della proprieta e costituito 
da tipi che C++Builder e in grado di salvare e caricare, utilizzare questo metodo. 

• Creare due metodi di tipo TStreamProc, uno per memorizzare e uno per caricare il 
valore della proprieta. TStreamProc richiede come un argomento uno stream, ed e 
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possibile utilizzare i metodi dello stream per scrivere e leggere i valori della 
proprieta. 

Per esempio, si immagini una proprieta che rappresenta un componente creato in 
fase di esecuzione. C++Builder sa come scrivere questo valore, ma non e in grado di 
farlo automaticamente perche il componente non e stato creato da Form Designer. 
Poiche il sistema di stream e gia in grado di caricare e salvare componenti, e possibile 
utilizzare il primo metodo.I metodi seguenti caricano e memorizzano il componente 
creato dinamicamente che rappresenta il valore di una proprieta di nome 
MyCompProperty: 

void __fastcall TSampleComponent : :LoadCompProperty (TReader *Reader) 

{ 

if (Reader->ReadBoolean() ) 
MyCompProperty = Reader->ReadComponent (NULL) ; 

} 

void __fastcall TSampleComponent: : StoreCompProperty (TWriter *Writer) 

{ 

if (MyCompProperty) 
{ 

Writer->WriteBoolean(true) ; 
Writer->WriteComponent (MyCompProperty) ; 

} 

else 

Writer->WriteBoolean (false) ; 

} 

Ridefinizione del metodo DefineProperties 

Una volta creati i metodi per memorizzare e caricare il valore della proprieta, e 
possibile ridefinire il metodo DefineProperties del componente. C++Builder chiama 
questo metodo quando carica o registra il componente. Nel metodo DefineProperties, 
si deve chiamare il metodo DefineProperty o il metodo DefineBinaryProperty del filer 
corrente, passandogli il metodo da utilizzare per caricare o per salvare il valore della 
proprieta. Se i metodi di registrazione e caricamento sono di tipo TWriterProc e di 
tipo TReaderProc, si chiamera il metodo DefineProperty del filer. Se i metodi creati 
sono di tipo TStreamProc, si chiamera invece DefineBinaryProperty. 

Indipendentemente dal tipo metodo utilizzato per definire la proprieta, lo si passa ai 
metodi che memorizzano e caricano il valore della proprieta, assieme ad un valore di 
tipo boolean che indica se il valore della proprieta deve essere scritto. Se il valore puo 
essere ereditato o ha un valore predefinito, non sara necessario scriverlo. 

Per esempio, dato il metodo LoadCompProperty di tipo TReaderProc e il metodo 
StoreCompProperty di tipo TWriterProc, si potrebbe ridefinire DefineProperties nel 
seguente modo: 

void fastcall TSampleComponent : :DefineProperties (TFiler *Filer) 

{ 

// before we do anything, let the base class define its properties. 

// Note that this example assumes that TSampleComponent derives directly from TComponent 
TComponent : :DefineProperties (Filer) ; 
bool WriteValue; 

if (Filer->Ancestor) // check for inherited value 
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{ 

if ( (TSampleComponent *)Filer->Ancestor) ->MyCompProperty == NULL) 

WriteValue = (MyCompProperty != NULL) ; 
else if ((MyCompProperty == NULL) II 

(((TSampleComponent *)Filer->Ancestor) ->MyCompProperty->Name != 

MyCompProperty->Name) ) 

WriteValue = true; 
else WriteValue = false; 

} 

else // no inherited value, write property if not null 

WriteValue = (MyCompProperty != NULL); 
Filer->DefmeProperty( "MyCompProperty 11 , LoadCompProperty, StoreCompProperty, WriteValue) ; 
end; 
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Capitolo 




Creazione di eventi 



Un evento e un collegamento tra un avvenimento nel sistema (ad esempio un'azione 
dell'utente o una modifica del fuoco) e una parte di codice che risponde a quel 
determinate avvenimento. II codice che risponde e un gestore di evento, e quasi 
sempre e scritto da chi sviluppa l'applicazione. Gli eventi consentono agli 
sviluppatori di personalizzare il comportamento dei componenti senza modificare le 
relative classi. Cio e noto come delegation. 

Gli eventi per le azioni piu comuni dell'utente (come le azioni del mouse) sono 
intrinseci a tutti i componenti standard, ma si possono definire anche nuovi eventi. 
Per creare eventi in un componente, e necessario capire quanta segue: 

• Cos'e un evento 

• Implementazione degli eventi standard 

• Definizione di eventi personalizzati 

Gli eventi sono implementati come proprieta e pertanto, prima di provare a creare o 
modificare gli eventi di un componente, si dovrebbe gia avere familiarita con gli 
argomenti trattati nel Capitolo 47, "Creazione di proprieta",. 

Cos'e un evento 



Un evento e un meccanismo che collega un avvenimento al codice. Piu esattamente, 
un evento e un closure che punta a un metodo in una determinata istanza della 
classe. 

Dal punto di vista dello sviluppatore di applicazioni, un evento e soltanto un nome 
che si riferisce a un avvenimento del sistema, come OnClick, a cui e possibile 
collegare una determinata sequenza di istruzioni. Per esempio, un pulsante di nome 
Buttonl, ha un metodo OnClick. Per impostazione predefinita, C++Builder genera un 
gestore di evento denominato ButtonlClick nella scheda che contiene il pulsante e lo 
assegna a OnClick. Quando nel pulsante si verifica un evento clic, il pulsante richiama 
il metodo assegnato a OnClick, in questo caso ButtonlClick. 
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Per scrivere un evento occorre capire quanta segue: 

• Gli eventi sono closure. 

• Gli eventi sono proprieta. 

• I tipi degli eventi sono tipi closure. 

• II tipo restituito dai gestori di evento e void 

• I gestori di evento sono facoltativi. 

Gli eventi sono closure 



C++Builder utilizza i closure per implementare gli eventi. Un closure e un tipo 
speciale di puntatore che punta ad un certo metodo in una certa istanza di una classe. 
Chi scrive componenti puo trattare il closure come un segnaposto. II programma 
rileva il verificarsi di un evento, e pertanto chiama (se esiste) il metodo specificato 
dall'utente per quell'evento. 

I closure mantengono un puntatore nascosto a un'istanza della classe. Quando 
l'utente assegna un gestore all'evento di un componente, l'assegnazione non e 
soltanto a un metodo con un determinato nome, ma piuttosto a un metodo specifico 
di una specifica istanza di una classe. Questa istanza e di solito la scheda contenente 
il componente, ma non necessariamente. 

Tutti i controlli, per esempio, ereditano un metodo virtuale di nome Click per gestire 
gli eventi clic: 

virtual void fastcall Click(void) ; 

L'implementazione di Click chiama il gestore di eventi clic dell'utente, se ne esiste 
uno. Se l'utente ha assegnato un gestore a un evento OnClick del controllo, facendo 
clic sul controllo viene chiamato quel metodo. Se non e stato assegnato nessun 
gestore, non accade nulla. 

Gli eventi sono proprieta 



I componenti usano le proprieta per implementare i propri eventi. A differenza della 
maggior parte delle proprieta, gli eventi non usano metodi per implementare le 
proprie parti read e write. Invece, le proprieta dell'evento usano un membro dati 
privato della classe il cui tipo e uguale a quello della proprieta. 

Per convenzione, il nome del membro dati e lo stesso nome della proprieta, ma 
preceduto dalla lettera F. Ad esempio, il closure OnClick e memorizzato in un 
membro dati di nome FOnClick di tipo TNotifyEvent e la dichiarazione della proprieta 
evento OnClick e simile alia seguente: 

class PACKAGE TControl : public TComponent 
{ 

private: 

TNotifyEvent FOnClick; 

protected: 

__property TNotifyEvent OnClick = {read=FOnClick, write=FOnClick} ; 
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}; 

Per saperne di piu su TNotifyEvent e sugli altri tipi di evento, vedere la prossima 
sezione "I tipi degli eventi sono tipi closure". 

valore deU'evento anche durante l'esecuzione. II vantaggio principale della gestione 
degli eventi come proprieta, comunque, e che l'utente del componente pud assegnare 
all'evento un gestore durante lo sviluppo usando Object Inspector. 

I tipi degli eventi sono tipi closure 



Poiche un evento e un puntatore a un gestore di eventi, il tipo della proprieta 
deU'evento deve essere un closure. Analogamente, il codice usato per gestire l'evento 
deve essere il metodo di una classe, di tipo appropriato. 

Per essere compatibile con un evento di un certo tipo, il metodo di gestione evento 
deve avere lo stesso numero e tipo di parametri, nello stesso ordine e passati nello 
stesso modo. 

C++Builder definisce i closure per tutti i suoi eventi standard. Quando il 
programmatore crea i propri eventi, puo utilizzare un closure esistente, se e 
appropriato, o definirne uno proprio. 

II tipo restituito dai gestori di evento e void 

II tipo restituito dai gestori di evento puo essere solo di tipo void. Anche se i gestori 
possono restituire solo tipi void, e sempre possibile ottenere dai codice utente delle 
informazioni di ritorno passando gli argomenti per riferimento. Se si adotta questo 
metodo, occorre accertarsi di assegnare all'argomento un valore consentito prima di 
effettuare la chiamata, in modo che non sia necessario che il codice dell'utente 
modifichi il valore. 

Un esempio del passaggio degli argomenti per riferimento a un gestore di evento e 
l'evento legato alia pressione dei tasti, di tipo TKeyPressEvent. TKeyPressEvent 
definisce due argomenti, il primo indicante l'oggetto che ha generato l'evento, e 
l'altro indicante il tasto premuto: 

typedef void fastcall ( closure *TKeyPressEvent) (TObject *Sender, Char &Key) ; 

Normalmente, il parametro Key contiene il carattere premuto dall'utente. In 
determinate circostanze, tuttavia, l'utente del componente potrebbe decidere di 
cambiare il carattere. Un esempio potrebbe essere quello di forzare tutti i caratteri in 
maiuscolo in un controllo per l'editing. In questo caso l'utente potrebbe definire il 
seguente gestore per la pressione dei tasti: 

void __fastcall TForml: :EditlKeyPress (TObject *Sender, Char &Key) 
{ 

Key = UpCase(Key) ; 

} 

E anche possibile utilizzare argomenti passati per riferimento in modo da consentire 
all'utente di ridefinire la gestione predefinita. 
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I gestori di evento sono facoltativi 



Nella creazione di eventi, occorre ricordare che gli sviluppatori che utilizzano i 
componenti sviluppati da altri potrebbero non collegare ad essi un gestore di eventi. 
Cio significa che il componente non dovrebbe bloccarsi o generare errori solo perche 
a un particolare evento non e collegato un gestore. (I meccanismi di chiamata di un 
gestore evento e le modalita operative con eventi che non hanno un gestore di eventi 
collegato sono spiegati nella sezione "Chiamata dell'evento" a pagina 48-9.) 

Gli eventi si verificano quasi ininterrottamente in un'applicazione GUI. II semplice 
spostamento del puntatore del mouse su un componente visuale, provova la 
trasmissione di numerosi messaggi di movimento mouse che il componente traduce 
in eventi OnMouseMove. Nella maggior parte dei casi, gli sviluppatori non vogliono 
gestire gli eventi di movimento del mouse, e cio non dovrebbe comportare problemi. 
Percio i componenti creati non dovrebbero prevedere un gestore per il trattamento 
dei relativi eventi. 

Inoltre, gli sviluppatori di applicazioni possono scrivere una qualsiasi sequenza di 
istruzioni in un gestore di evento. I componenti nella VCL hanno eventi scritti in 
modo da minimizzare i rischi che un gestore di evento possa generare errori. 
Naturalmente, e impossibile garantirsi contro errori di logica nel codice 
dell'applicazione, ma si puo fare in modo di controllare che le strutture dati vengano 
inizializzate prima di effettuare chiamate agli eventi, in modo che chi sviluppa non 
possa accedere a dati non validi. 

Implementazione degli eventi standard 



I controlli forniti con C++Builder ereditano gli eventi per gli awenimenti piu 
frequenti. Questi sono chiamati eventi standard. Benche tutti questi eventi siano 
inclusi nei controlli, spesso sono protected, vale a dire che gli sviluppatori non 
possono collegare ad essi alcun gestore di eventi. Quando si crea un controllo, e 
possibile scegliere se rendere visibili gli eventi agli utenti del controllo. 

Vi sono tre aspetti da considerare quando si incorporano gli eventi standard 
all'intemo del controllo: 

• Identificazione degli eventi standard 

• Visibilita degli eventi 

• Modifica della gestione standard degli eventi 

Identificazione degli eventi standard 



Esistono due categorie di eventi standard: quelli definiti per tutti i controlli e quelli 
definiti solo per i controlli standard per finestra. 
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Eventi standard di tutti i controlli 

Gli eventi piu comuni sono definiti nella classe TControl. Tutti i controlli, siano essi 
per finestra, grafici o personalizzati, ereditano questi eventi. I seguenti eventi sono 
disponibili in tutti i controlli: 

OnClick OnDragDrop OnEndDrag OnMouseMove 

OnDblCHck OnDragOver OnMouseDown OnMousellp 

Gli eventi standard hanno metodi virtual protected corrispondenti dichiarati in 
TControl, con nomi che corrispondono ai nomi deU'evento. Per esempio, gli eventi 
OnClick chiamano un metodo di nome Click, mentre gli eventi OnEndDrag chiamano 
un metodo di nome DoEndDrag. 

Gli eventi standard dei controlli standard 

Oltre agli eventi comuni a tutti i controlli, i controlli con finestra standard (quelli che 
derivano da TWinControl nella VCL e TWidgetControl nella CLX) possiedono i 
seguenti eventi: 

OnEnter OnKeyDown OnKeyPress 

OnKeyllp OnExit 

Analogamente agli eventi in TControl, anche gli eventi dei controlli con finestra 
hanno metodi corrispondenti. Gli eventi standard di tastiera elencati in precedenza 
rispondono a tutte le normali pressioni dei tasti. 

Comunque, per rispondere a speciali combinazioni di tasti (come quelle con il tasto 
Alt), e necessario rispondere al messaggio WM_GETDLGCODE o 
CM_WANTSPECIALKEYS da Windows. Per informazioni sulla scrittura dei gestori 
di messaggi vedere il Capitolo 51, "Gestione dei messaggi e delle notifiche di 
sistema". 

Visibility degli eventi 



Le dichiarazioni degli eventi standard in TControl e TWinControl {TWidgetControl 
nella CLX) sono protette, come lo sono i metodi ad essi corrispondenti. Se si sta 
ereditando da una di queste classi astratte e si vogliono rendere accessibili i relativi 
eventi in esecuzione o in progettazione, occorre ridichiarare gli eventi come public o 
published. 

La ridichiarazione di una proprieta senza specificarne l'implementazione mantiene 
invariati i metodi d'implementazione, ma modifica il livello di protezione. E quindi 
possibile prendere un evento definito in TControl ma che non e stato reso visibile, e 
renderlo tale dichiarandolo public o published. 

Ad esempio, per creare un componente che rende visibile l'evento OnClick in fase di 
progetto, si potrebbe aggiungere quanto segue alia dichiarazione della classe del 
componente. 

class PACKAGE TMyControl : public TCustomControl 
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{ 

__published: 

property Onclick; // Makes Onclick available in the Object Inspector 

}; 

Modifica della gestione standard degli eventi 



IVolendo modificare il modo in cui il componente risponde a determinati tipi di 
evento, si potrebbe essere tentati di scrivere una certa sequenza di istruzioni e 
assegnarla all'evento. Come sviluppatori di applicazioni, e esattamente quello si 
farebbe. Ma quando si crea un componente, occorre mantenere l'evento disponibile 
per gli sviluppatori che utilizzeranno il componente. 

Questo e il motivo dei metodi di implementazione protetti, associati a ognuno degli 
eventi standard. Ridefinendo il metodo di implementazione, e possibile cambiare la 
gestione interna dell'evento; e chiamando il metodo ereditato, e possibile conservare 
la gestione standard, incluso l'evento per il codice dello sviluppatore di applicazioni. 

L'ordine in cui si chiamano i metodi e importante. Come regola, occorre chiamare 
prima il metodo ereditato, consentendo che l'esecuzione del gestore di evento 
previsto dallo sviluppatore dell'applicazione avvenga prima della propria 
personalizzazione (e, in alcuni casi, impedendo che avvenga). Possono comunque 
verificarsi casi in cui si vuole che il proprio codice venga eseguito prima di chiamare 
il metodo ereditato. Per esempio, se il codice ereditato e in qualche modo dipendente 
dallo stato del componente e il proprio codice modifica lo stato, occorrerebbe 
effettuare le modifiche e poi consentire al codice dell'utente di rispondere ad esse. 

Si supponga che si stia scrivendo un componente e si voglia modificare il modo con 
cui risponde al clic del mouse. Invece di assegnare un gestore all'evento OnClick 
come farebbe uno sviluppatore di applicazioni, si puo sostituire il metodo Click 
protetto: 

void __fastcall TMyControl: : Click () 

{ 

TWinControl :: Click () ; // perform standard handling, including calling handler 

// your customizations go here 

} 



Definizione di eventi personalizzati 



La definizione di eventi completamente nuovi e una cosa abbastanza insolita. Ci sono 
comunque situazioni in cui, quando un componente presenta un comportamento 
completamente diverso da quello di qualsiasi altro componente, e necessario definire 
un evento specifico. 

Nella definizione di un evento vanno considerati i seguenti aspetti: 

• Attivazione dell'evento 

• Definizione del tipo di gestore 
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• Dichiarazione dell'evento 

• Chiamata dell'evento 

Attivazione dell'evento 



Occorre sapere che cosa provoca l'attivazione di un evento. Per alcuni eventi, la 
risposta e ovvia. Per esempio, tin evento mouse-down si verifica quando l'utente 
preme il pulsante sinistra del mouse e Windows invia un messaggio 
WM_LBUTTONDOWN all'applicazione. Alia ricezione di questo messaggio, un 
componente chiama il proprio metodo MouseDown che, a sua volta, chiama il codice 
che l'utente ha associato all'evento OnMouseDown. 

Ma ci sono eventi chiaramente dipendenti da specifici avvenimenti esterni. Per 
esempio, un evento OnChange della barra di scorrimento e provocato da avvenimenti 
di vario genere, inclusi la pressione di tasti, il clic del mouse o modifiche in altri 
controlli. Nella definizione degli eventi bisogna garantire che tutti gli avvenimenti 
richiamino in modo appropriato i rispettivi eventi. 

Per le applicazioni CLX, vedere "Risposta alle notifiche di sistema utilizzando la 
CLX" a pagina 51-11. 

Due tipi di eventi 

Vi sono due tipi di avvenimenti per cui sarebbe necessario prevedere eventi: 
interazioni dell'utente e cambiamenti di stato. Gli eventi di interazione dell'utente 
sono quasi sempre attivati da un messaggio di Windows, che indica che l'utente ha 
fatto qualcosa cui il componente potrebbe dover rispondere. Gli eventi di 
cambiamenti di stato possono anch'essi essere correlati a messaggi di Windows 
(cambiamento o attivazione del fuoco, per esempio), ma possono verificarsi anche 
per modifiche alle proprieta o in altre situazioni. 

Occorre avere il controllo totale di cio che puo attivare un evento definite Bisogna 
definire con precisione gli eventi, in modo che gli sviluppatori siano in grado di 
capirli e di utilizzarli 

Definizione del tipo di gestore 



Una volta determinato quando si verifica l'evento, occorre definire come deve essere 
gestito l'evento. Cio significa stabilire il tipo di gestore di evento. Nella maggior parte 
dei casi i gestori degli eventi definiti da chi programma sono semplici notifiche 
oppure tipi che dipendono dell'evento. E anche possibile fare in modo che il gestore 
restituisca delle informazioni. 

Notifica semplice 

Un evento di notifica informa che l'evento e accaduto, ma non dice quando o dove e 
accaduto. Le notifiche utilizzano il tipo TNotifyEvent, che prevede un solo parametro, 
e cioe chi ha scatenato l'evento. Tutto cio che gestore di una notifica "conosce" a 
proposito dell'evento e il tipo di evento e per quale componente l'evento si e 
verificato. Per esempio, gli eventi clic sono notifiche. Quando si scrive un gestore per 
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un evento clic tutto cio che si sa e che si e verificato un clic e su quale componente e 
stato fatto clic. 

La notifica e un processo monodirezionale. Non esiste alcun meccanismo per fornire 
informazioni di ritorno o per prevenire un'ulteriore gestione di una notifica. 

Gestori che dipendono dall'evento 

In alcuni casi non e sufficiente conoscere quale evento si e verificato e su quale 
componente si e verificato. Per esempio, se l'evento e legato alia pressione di un 
tasto, e probabile che il gestore di eventi voglia sapere qual e il tasto premuto 
dall'utente. In questi casi occorrono dei tipi di gestore che includano parametri per 
informazioni aggiuntive. 

Se l'evento e stato generato in risposta a un messaggio, e probabile che i parametri 
passati al gestore dell'evento siano presi direttamente dai parametri del messaggio. 

Restituzione di informazioni da parte del gestore 

Poiche tutti i gestori di evento restituiscono solo void, il solo modo che ha un gestore 
per restituire informazioni e tramite parametri passati per riferimento. I componenti 
potranno utilizzare queste informazioni per determinare come o se trattare l'evento, 
una volta terminata l'esecuzione del gestore definito dall'utente. 

Ad esempio, tutti gli eventi relativi ai tasti (OnKeyDown, OnKeyllp e OnKeyPress) 
passano per riferimento il valore del tasto premuto in un parametro var di nome Key. 
II gestore di evento puo modificare Key in modo che l'applicazione riconosca come 
tasto implicato nell'evento un tasto diverso da quello utilizzato. Questo e, ad 
esempio, il modo per forzare la scrittura di caratteri in maiuscolo. 

Dichiarazione dell'evento 



Una volta determinate il tipo di gestore evento, si puo iniziare a dichiarare il closure 
e le proprieta dell'evento. E consigliabile utilizzare dei nomi significativi e descrittivi 
in modo che l'utente possa capire a cosa serve l'evento. E anche importante la 
coerenza e quindi bisogna cercare di dare nomi analoghi a quelli delle proprieta 
simili di altri componenti. 

I nomi degli eventi cominciano con 'On" 

The I nomi di molti eventi in C++Builder cominciano con "On". Questa e soltanto 
una convenzione; il compilatore non impone di attenervisi. L'Object 
Inspectordetermina che una proprieta e un evento esaminando il tipo della proprieta: 
tutte le proprieta di closure vengono considerate eventi e appaiono nella pagina 
Events. 

Gli sviluppatori si aspettano di trovare gli eventi nell'elenco alfabetico dei nomi che 
cominciano con "On". Usando altri tipi di nomi, si rischierebbe di confonderli. 

L'eccezione principale a questa regola e che molti eventi che si verificano prima di e 
dopo un certo accadimento iniziano con "Before" e "After". 
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Le chiamate a un evento dovrebbero essere centralizzate. Cioe, si dovrebbe creare nel 
componente un metodo virtual che chiami il gestore di eventi dell'applicazione (se ne 
e stato assegnato uno) e che fornisca la gestione predefinita. 

Collocare tutte le chiamate dell'evento in un punto garantisce che chiunque derivi un 
nuovo componente possa personalizzare la gestione dell'evento sovrapponendosi a 
un unico metodo, anziche ricercare in tutto il programma tutte le posizioni da cui 
viene chiamato l'evento. 

Vi sono due altre considerazioni da fare quando si chiama l'evento: 

• I gestori di evento vuoti devono essere validi. 

• Gli utenti possono ridefinire la gestione predefinita. 

I gestori di evento vuoti devono essere validi 

Non si dovrebbe mai creare una situazione in cui un gestore evento vuoto possa 
causare un errore, nemmeno se il funzionamento corretto del componente dipende 
da una particolare risposta derivante dal codice di gestione evento dell'applicazione. 

Un gestore di evento vuoto dovrebbe produrre lo stesso risultato che si avrebbe se 
non ci fosse alcun gestore evento. Percio la sequenza di istruzioni per chiamare il 
gestore di evento di un'applicazione dovrebbe apparire cosi: 

if (OnClick) 

OnClick (this) ; 
// perform default handling } 

Non si dovrebbe mai avere un codice simile al seguente: 

if (OnClick) 

OnClick(this) ; 
else 

// perform default handling 

Gli utenti possono ridefinire la gestione predefinita 

Per alcuni tipi di eventi lo sviluppatore potrebbe voler sostituire la gestione 
predefinita, o addirittura sopprimere tutte le risposte. Per fare cio, e necessario 
passare per riferimento un argomento al gestore di evento e, al ritorno dal gestore, 
controllare un determinato valore. 

Questo e in linea con la regola che un gestore di evento vuoto dovrebbe produrre lo 
stesso effetto che si avrebbe se non ci fosse alcun gestore di evento. Poiche un gestore 
vuoto non modifichera i valori degli argomenti passati per riferimento, la gestione 
predefinita verra attivata sempre dopo avere chiamato il gestore vuoto. 

Ad esempio, quando si gestiscono gli eventi legati alia pressione dei tasti, l'utente 
puo sopprimere la gestione predefinita della pressione del tasto effettuata dal 
componente impostando il parametro Key a un carattere NULL.La logica per 
supportare cio e simile all'esempio seguente: 

if (OnKeyPress) 
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OnKeyPress (this, &Key) ; 
if (Key != NULL) 
//perform default handling 

II codice vero e proprio sara leggermente diverso da questo in quanta deve trattare i 
messaggi di Windows, ma la logica e la stessa. Per impostazione predefinita, il 
componente chiama qualsiasi gestore assegnato dall'utente e poi esegue la sua 
gestione standard. Se il gestore definito dall'utente imposta Key a un carattere NULL, 
il componente non esegue la gestione predefinita. 
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Creazione di metodi 



I metodi dei componenti non sono molto differenti dai metodi delle altre classi. Cio 
significa che essi sono funzioni membro incorporate nella struttura della classe di un 
componente. Benche non vi siano sostanziali restrizioni su cio che e possibile fare con 
i metodi di un componente, C++Builder utilizza alcuni standard che andrebbero 
seguiti. Questi sono: 

• Eliminazione delle dipendenze 

• Assegnazione del nome ai metodi 

• Protezione dei metodi 

• Utilizzo dei metodi virtual 

• Dichiarazione dei metodi 

In generale, i componenti non dovrebbero contenere molti metodo e si dovrebbe 
ridurre al minimo il numero di metodi che un'applicazione deve chiamare. Le 
caratteristiche che si sarebbe tentati di implementare come metodi spesso vengono 
incapsulati meglio nelle proprieta. Le proprieta mettono a disposizione un'interfaccia 
adatta all'ambiente di C++Builder e sono accessibili in fase di progetto. 

Eliminazione delle dipendenze 



Quando si scrive il codice di un componente e auspicabile ridurre al minimo le 
precondizioni imposte alio sviluppatore. Per quanto possibile, gli sviluppatori 
dovrebbero poter utilizzare il componente in qualsiasi contesto e in qualsiasi 
momento. Ci saranno certamente circostanze in cui non sara possibile soddisfare 
questa regola, ma l'obiettivo di chi sviluppa componenti e quello di attenervisi il piu 
possibile. 

Questo elenco da un'idea dei tipi di dipendenze da evitare: 

• Metodi che l'utente deve richiamare per utilizzare il componente 

• Metodi che vanno eseguiti rispettando una particolare sequenza 
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• Metodi che mettono il componente in uno stato o in una condizione in cui 
determinati eventi o metodi possono risultare non validi 

II migliore modo per gestire queste situazioni e quello di fornire un metodo per 
uscirne. Per esempio, se chiamando un metodo si mette il componente in un stato che 
risulterebbe non valido se si chiamasse un altro metodo, occorre scrivere quel 
secondo metodo in modo tale che corregga lo stato del componente nel caso venga 
chiamato da un'applicazione quando lo stato del componente non e corretto, prima 
di eseguire il codice principale. Come minimo, si dovrebbe sollevare un'eccezione nei 
casi in cui un utente chiama un metodo che non e valido. 

In altri termini, se si crea una situazione in cui delle parti di codice dipendono l'una 
dall'altra, il programmatore dovrebbe farsene carico per evitare che un utilizzo 
scorretto del codice non provochi problemi. Per esempio, nel caso in cui l'utente non 
rispetti le dipendenze imposte, un messaggio di segnalazione e preferibile a un 
errore di sistema. 

Assegnazione del nome ai metodi 



C++Builder non impone restrizioni sui nomi assegnati ai metodi o ai rispettivi 
parametri. Vi sono comunque alcune convenzioni che semplificano l'uso dei metodi 
a chi sviluppa applicazioni. E bene ricordare che e la stessa architettura a componenti 
che fa si che i componenti sviluppati possano essere utilizzati da vari tipi di utenti. 

Chi e abituato a scrivere codice per uso personale o per un piccolo gruppo di 
programmatori potrebbe essere tentato di trascurare questo aspetto della 
programmazione. E comunque consigliabile cercare di rendere i nomi dei metodi piu 
chiari possibile, in modo che anche le persone che non hanno familiarita con il codice 
(o addirittura con la programmazione in assoluto), siano poste in condizione di usare 
i componenti. 

Ecco alcuni suggerimenti per rendere piu chiari i nomi dei metodi: 

• Usare nomi descrittivi. Utilizzare verbi significativi. 

Un nome come PasteFromClipboard offre molte piu informazioni di un semplice 
Paste o PFC. 

• I nomi delle funzioni dovrebbero riflettere la natura del risultato restituito. 

Puo anche sembrare ovvio che una funzione chiamata X restituisca la posizione 
orizzontale sullo schermo di un elemento, ma un nome come GetHorizontalPosition 
e piu facilmente comprensibile. 

• Se il tipo restituito da una funzione e void, il nome della funzione dovrebbe essere 
attivo. 

Nei nomi delle funzioni si consiglia l'utilizzo di verbi attivi. Ad esempio, 
ReadFileNames e molto piu comprensibile di DoFiles. 

Una considerazione finale: verificare che il metodo debba essere necessariamente un 
metodo. Una regola empirica e che il nome del metodo contenga un verbo. Se si 
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scopre che si stanno creando molti metodi il cui nome non contiene un verbo, e bene 
prendere in esame il fatto se trasformare tutti questi metodi in proprieta. 

Protezione dei metodi 



Tutte le parti delle classi, compresi i membri dei dati, i metodi e le proprieta hanno 
un livello di protezione o di "visibilita", come spiegato nella sezione "Controllo 
deU'accesso" a pagina 46-4. Scegliere il tipo di visibilita appropriata per un 
determinato metodo e semplice. 

La maggior parte dei metodi che lo sviluppatore scrive nei componenti sono public o 
protected. Raramente si presenta la necessita di rendere private un metodo, a meno 
che non sia veramente specifico per quel tipo di componente, al punto che anche i 
componenti derivati non possono avere accesso ad esso. 

Di solito, non c'e alcun motivo per dichiarare un metodo (ad eccezione di un gestore 

di evento) come published. Cosi facendo, dal punto di vista dell'utente, sarebbe 

come se il metodo fosse stato dichiarato public. 

Metodi che devono essere pubblici 



Tutti i metodi che gli sviluppatore di applicazioni hanno bisogno di richiamare 
devono essere dichiarati public. Si deve tenere presente che la maggior parte delle 
chiamate ai metodi avviene nei gestori di eventi, per cui i metodi dovrebbe evitare di 
creare vincoli alle risorse del sistema o di mettere il sistema operativo in condizione 
di non poter rispondere all'utente. 

I costruttori e i distruttori devono essere sempre public. 



Metodi che devono essere protetti 



Ogni metodo implementato per un componente deve essere dichiarato protected in 
modo tale che le applicazioni non lo possano chiamare al momento sbagliato. Se si 
hanno dei metodi che non devono essere chiamati dal codice dell'applicazione, ma 
che sono chiamati da classi derivate, bisogna dichiararli protected. 

Ad esempio, si supponga di avere un metodo che prevede la preimpostazione di 
alcuni dati. Se si rende public tale metodo, esiste la possibility che applicazioni lo 
chiamino prima che i dati siano stati impostati. D'altra parte, rendendolo protected si 
e sicuri che le applicazioni non lo possano chiamare direttamente. Si possono, quindi, 
impostare altri metodi public, in modo da assicurare che l'impostazioni dei dati 
avvenga prima della chiamata al metodo protected. 

I metodi che implementano le proprieta devono essere dichiarati metodi virtual 
protected. I metodi cosi dichiarati permettono agli sviluppatori di applicazioni di 
ridefinire l'implementazione della proprieta, aumentandone la funzionalita o 
sostituendola completamente. Tali proprieta sono completamente polimorfe. 
Mantenendo i metodi di accesso protected, si ha la certezza che gli sviluppatori non li 
possano chiamare accidentalmente, modificando inawertitamente una proprieta. 
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Utilizzo dei metodi virtual 



I metodi vengono resi virtual quando si vuole che tipi differenti siano in grado di 
eseguire sequenze di istruzioni diverse in risposta alia stessa chiamata di metodo. 

Se si creano componenti destinati a essere utilizzati direttamente da chi sviluppa 
applicazioni, e possibile rendere non virtual tutti i metodi. D'altra parte, se si creano 
componenti astratti da cui saranno derivati altri componenti, e bene rendere virtual i 
metodi aggiunti. In questo modo, i componenti derivati possono ridefinire i metodi 
virtual ereditati. 

Dichiarazione dei metodi 



La dichiarazione di un metodo in un componente e analoga alia dichiarazione di un 
qualsiasi metodo di una classe. 

Per dichiarare un nuovo metodo in un componente, si deve fare quanto segue: 

• Aggiungere la dichiarazione del metodo alia dichiarazione della classe del 
componente nel file header del componente. 

• Scrivere nel file .CPP della unit il codice che implementa il metodo. 

II codice seguente mostra un componente che definisce due nuovi metodi, un metodo 
protected e un metodo virtual public. Quella che segue e la definizione nel file .H 
dell'interfaccia: 

class PACKAGE TSaropleComponent : public TControl 

{ 

protected: 

void __fastcall MakeBiggerO ; 
public: 

virtual int __fastcall CalculateArea ( ) ; 

}; 

Quello che segue e il codice, incluso nel file .CPP, che implementa i metodi: 

void __fastcall TSampleComponent: : MakeBiggerO 

{ 

Height = Height + 5; 
Width = Width + 5; 

} 

int __fastcall TSampleComponent : :CalculateArea ( ) 

{ 

return Width * Height; 

} 
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Uso della grafica nei 



componenti 



Windows dispone di una potente interfaccia GDI (graphics device interface) per 
disegnare grafici indipendenti dal dispositive La GDI richiede al programmatore 
ulteriori requisiti, come ad esempio la gestione delle risorse grafiche. C++Builder si 
fa carico di tutte le fastidiose incombenze necessarie alia GDI, permettendo di 
concentrarsi sul lavoro produttivo invece di andare alia ricerca di handle persi o di 
risorse non rilasciate. 

Le funzioni GDI, come qualsiasi parte delle API di Windows, possono essere 
chiamate direttamente dall'applicazione C++Builder. Molto probabilmente, pero, si 
notera che e piu rapido e semplice usare l'incapsulamento delle funzioni grafiche di 
C++Builder. 

Le funzioni GDI sono specifiche per Windows e non sono utilizzabili in ambiente 
CLX o per applicazioni multipiattaforma. Tuttavia, i componenti CLX utilizzano una 
libreria Qt. 

Gli argomenti trattati in questa sezione includono: 

• Introduzione alia grafica 

• Utilizzo del canvas 

• Operazioni con le immagini 

• Le bitmap fuori schermo 

• Risposta alle modifiche 



C++Builder incapsula la GDI di Windows (QT di CLX) in vari modi. L'aspetto piu 
significativo per lo sviluppatore di componenti e il modo in cui il componente mostra 
la propria immagine sullo schermo. Quando viene chiamata direttamente una 
funzione GDI, e necessario avere un handle per un contesto di dispositivo, all'intemo 
del quale vengono selezionati gli strumenti di disegno come la penna, il pennello e il 
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font. Una volta terminata la realizzazione dell'immagine, il programmatore deve 
personalmente riportare il device context alio stato originario e poi rilasciarlo. 

Anziche obbligare ad operare sulla grafica a livelli particolareggiati, C++Builder 
fornisce un'interfaccia semplice ma molto completa: la proprieta Canvas di un 
componente. II canvas garantisce di avere sempre disponibile un device context 
valido, che viene rilasciato non appena si e finito di usarlo. Analogamente, il canvas 
ha una serie di proprieta specifiche che rappresentano la penna, il pennello e il font 
correnti. 

Poiche il canvas gestisce automaticamente tutte queste risorse, lo sviluppatore di 
componenti non deve preoccuparsi di creare, selezionare e rilasciare direttamente 
cose come gli handle di penna. E sufficiente ordinare al canvas di utilizzare un certo 
tipo di penna e il canvas si occupera del resto. 

Uno dei benefici della gestione delle risorse grafiche da parte di C++Builder sta nel 
fatto che C++Builder puo mettere le risorse nella cache, velocizzando notevolmente 
le operazioni ripetitive. Per esempio, se si sta creando un'applicazione che 
ripetutamente genera, utilizza e rilascia un particolare tipo di penna, non e necessario 
ripetere tutte queste operazioni ogni volta all'interno di un ciclo. C++Builder, infatti, 
salva le risorse grafiche all'interno della cache; in questo modo non deve ricreare lo 
strumento, ma si limita a riutilizzarne uno esistente. 

Un esempio di quanta detto puo essere una applicazione che ha dozzine di schede 
aperte, con centinaia di controlli. Ognuno di questi controlli puo avere una o piu 
proprieta TFont. Anche se cio puo generare centinaia o migliaia di istanze di oggetti 
TFont, la maggior parte delle applicazioni tende ad utilizzare solo due o tre handle di 
font grazie alia cache per i font. 

Di seguito sono riportati due esempi che illustrano quanto sia semplice la codifica 
della grafica con C++Builder. II primo esempio usa le funzioni GDI standard per 
disegnare un'ellisse gialla tracciata su sfondo blu nella finestra, secondo una tecnica 
adottata con altri strumenti di sviluppo. II secondo usa un canvas per disegnare la 
stessa ellisse in un'applicazione scritta con C++Builder. 

Questo e il codice ObjectWindows: 

void TMyWindow: : Paint (TDC& PaintDC, bool erase, TRect& rect) 

{ 

HPEN PenHandle, OldPenHandle; 

HBRUSH BrushHandle, OldBrushHandle; 

PenHandle = CreatePen(PS_SOLID, 1, RGB ( , 0, 255)); 

OldPenHandle = SelectObject (PaintDC, PenHandle); 

BrushHandle = CreateSolidBrush(RGB(255, 255, 0)); 

OldBrushHandle = SelectObject (PaintDC, BrushHandle); 

EllipsedO, 20, 50, 50); 

SelectObject (OldBrushHandle) ; 

DeleteObject (BrushHandle) ; 

SelectObject (OldPenHandle) ; 

DeleteObject (PenHandle) ; 

) 

Questo e il codice C++Builder che svolge esattamente lo stesso compito: 

void fastcall TForml: :FormPamt (TObject *Sender) 
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{ 

Canvas->Pen->Color = clBlue; 
Canvas->Brush->Color = clYellow; 
Canvas->Ellipse(10, 20, 50, 50); 

} 



Utilizzo del canvas 



La classe canvas incapsula controlli grafici a vari livelli, fra cui funzioni ad alto livello 
per tracciare singole linee, figure e testo, proprieta intermedie per gestire le capacita 
di disegno del canvas, e, nella VCL, consente l'accesso a basso livello alia GDI di 
Windows. 

La Tabella 50.1 riassume le capacita del canvas. 



Tabella 50.1 Riepilogo delle capacita del canvas 
Operazione 

Disegno di linee e figure 

Visualizzazione e 
dimensionamento del testo 

Riempimento dell'area 

Personalizzazione di testo e 
grafica 

Trattamento dei pixel 
Copia e fusione di immagini 



Livello 

Alto 



Intermedio 



Basso 



Chiamata di funzioni della GDI di 
Windows 



Strumenti 

Metodi MoveTo, LineTo, Rectangle, e Ellipse 

Metodi TextOut, TextHeight, TextWidth, e 
TextRect 

Metodi FillRect e FloodFill 
Proprieta Pen, Brush, e Font 

Proprieta Pixels. 

Metodi Draw, StretchDraw, BrushCopy, e 
CopyRect; proprieta CopyMode 

Proprieta Handle 



Per informazioni piu dettagliate sulle classi canvas e sui relativi metodi e proprieta, 
consultare la Guida in linea. 



Operazioni con le immagini 



La maggior parte delle operazioni grafiche in C++Builder riguarda il disegno di 
componenti e di schede direttamente su canvas. C++Builder consente anche la 
gestione di immagini separate dai componenti, come bitmap, metafile e icone e 
gestisce automaticamente le tavolozze dei colori. 

Ci sono tre elementi importanti da tener presenti quando si lavora con le immagini in 
C++Builder: 

• Uso di classi picture, graphic o canvas 

• Caricamento e memorizzazione di grafici 

• Gestione delle tavolozze 
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Uso di classi picture, graphic o canvas 



In C++Builder ci sono tre tipi di classi che permettono di gestire la grafica: 

• Un canvas, che rappresenta una superficie disegnabile punto per punto sulla quale 
viene fatta apparire una scheda, un controllo grafico, una bitmap o una stampante. 
Un canvas e sempre una proprieta di un altro elemento e mai una classe a se 
stante. 

• Un elemento graphic rappresenta un'immagine grafica dello stesso tipo di quelle 
che si trovano normalmente all'interno di un file o di una risorsa, come una 
bitmap, un'icona o un metafile. C++Builder definisce le classi TBitmap, TIcon, e 
TMetafile (solo per VCL), tutte e tre derivate da una generica classe TGraphic. Lo 
sviluppatore puo anche definire proprie classi grafiche. Definendo un'interfaccia 
minima standard per tutti gli elementi grafici, Tgraphic mette a disposizione delle 
applicazioni un semplice meccanismo per operare facilmente con differenti tipi di 
elementi grafici. 

• Un elemento picture, che e un contenitore di un elemento grafico, nel senso che 
puo contenere una qualsiasi classe grafica. Per esempio, un elemento di tipo 
TPicture puo contenere una bitmap, un'icona, un metafile o un tipo di grafico 
definito dall'utente, e un'applicazione puo accedere a tutti questi elementi nello 
stesso modo attraverso la classe picture. Per esempio, i controlli immagine hanno 
una proprieta di nome Picture, di tipo TPicture, che consente al controllo di 
mostrare indifferentemente un'icona o un altro tipo di immagine. 

E bene tenere presente che una classe picture ha sempre un elemento graphic, che a 
sua volta potrebbe avere un canvas. (L'unico elemento grafico standard che ha un 
canvas e TBitmap). Di solito, quando si opera con un'immagine, si lavora solamente 
con le parti della classe grafica esposte tramite TPicture. Se serve poter accesso a 
specifici particolari della stessa classe grafica, si puo fare riferimento alia proprieta 
dell'immagine. 

Caricamento e memorizzazione di grafici 



Gli elementi picture e graphic di C++Builder possono caricare le proprie immagini 
da un file e salvarle nello stesso file o in un altro. II caricamento o il salvataggio delle 
immagini puo essere effettuato in qualsiasi momento. 

E anche possibile caricare e salvare immagini utilizzando una sorgente Qt MIME o 
un oggetto stream nel caso si stiano creando componenti CLX. 

Per caricare un'immagine da un file si deve chiamare il metodo LoadFromFile del 
componente picture. Per salvare un'immagine in un file, si deve chiamare il metodo 
SaveToFile del componente picture. 

LoadFromFile e SaveToFile accettano come unico parametro il nome del file. 
LoadFromFile utilizza l'estensione del nome del file per determinare il tipo di oggetto 
grafico che dovra creare e caricare. SaveToFile salva qualsiasi tipo di file purche 
appropriate al tipo di oggetto grafico che sta salvando. 
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Per caricare una bitmap all'interno di un controllo grafico, per esempio, si passa il 
nome di un file bitmap al metodo LoadFromFile del controllo: 

void fastcall TForml: :FormCreate(TObject *Sender) 

{ 

Imagel->Picture->LoadFromFile ( "c: WwindowsWathena.bmp" ) ; 

} 

L'oggetto picture riconosce l'estensione .bmp come estensione standard per i file 
bitmap, pertanto crea il proprio grafico come TBitmap e quindi chiama il metodo 
LoadFromFile del grafico. Poiche il grafico e una bitmap, carica l'immagine dal file 
sotto forma di bitmap. 

Gestione delle tavolozze 



Nel caso di componenti della VCL e della CLX, quando l'esecuzione del programma 
avviene su dispositivi basati su tavolozza (tipicamente, in modalita video a 256 
colori), C++Builder controlla automaticamente la realizzazione della tavolozza di 
supporto. Cioe se si ha un controllo che ha una tavolozza, si possono utilizzare i due 
metodi ereditati da TControl per controllare come Windows utilizza la tavolozza. 

II supporto delle tavolozza per i controlli presenta due aspetti: 

• Specifica di una tavolozza per un controllo 

• Risposta alle modifiche della tavolozza 

Molti controlli non hanno bisogno di una tavolozza, ma i controlli che contengono 
immagini grafiche "molto colorate" (come un controllo image) possono aver bisogno 
di interagire con Windows e con il driver dello schermo per assicurare un aspetto 
appropriate Windows fa riferimento a questo processo definendolo realizing delle 
tavolozze. 

II realizing delle tavolozze e il processo che garantisce che la finestra frontale utilizzi 
la tavolozza completa, mentre quelle di sfondo ne utilizzino il massimo possibile, 
mappando poi gli altri colori a quelli piu simili disponibili nella tavolozza "effettiva". 
Quando le finestre vengono spostate l'una di fronte all'altra, Windows esegue 
nuovamente il realizing. 

Anche C++Builder non fornisce un supporto specifico per creare o gestire le 
tavolozze, se non nel caso delle bitmap. Se si dispone di un handle di tavolozza, 
comunque, i controlli C++Builder sono in grado di gestirlo. 

Specifica di una tavolozza per un controllo 

Per specificare la tavolozza per un controllo della VCL e della CLX, ridefinire il 
metodo GetPalette del controllo affinche restituisca l'handle della tavolozza. 

Quando la tavolozza di un controllo viene specificata esplicitamente, awengono due 
cose: 

• L'applicazione viene informata che la tavolozza del controllo deve essere 
sottoposta al processo di realizing. 

• La tavolozza da usare nel realizing viene esplicitata. 
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Risposta alle modifiche della tavolozza 

Se un controllo della VCL e della CLX specifica una tavolozza ridefinendo GetPalette, 
C++Builder si occupa automaticamente di rispondere ai messaggi di Windows 
relativi alia tavolozza. II metodo che gestisce i messaggi relativi alle tavolozza e 
PaletteChanged. 

Lo scopo primario di PaletteChanged e determinare se il realizing della tavolozza del 
controllo deve avvenire in foreground o in background. Windows gestisce il realizing 
delle tavolozza facendo in modo che la finestra frontale abbia una tavolozza di 
foreground e che le altre finestre dispongano di tavolozze di background. 
C++Builder migliora questo trattamento poiche provvede al realizing delle tavolozze 
dei controlli che si trovano all'interno di una stessa finestra secondo la sequenza di 
accesso tramite il tasto TAB. L'unico caso in cui potrebbe essere necessario ridefinire 
questo comportamento predefinito e quando si desidera che un controllo, che non e il 
primo nella sequenza, abbia la tavolozza di foreground. 

Le bitmap fuori schermo 



Durante il disegno di immagini grafiche complesse, una comune tecnica nella 
programmazione grafica consiste nel creare una bitmap esternamente alio schermo, 
di tracciare l'immagine sulla bitmap e di copiare infine l'immagine completa dalla 
bitmap alia destinazione finale sullo schermo. L'utilizzo di questa tecnica riduce lo 
sfarfallio che sarebbe altrimenti causato dalle ripetute operazioni di disegno 
direttamente sullo schermo. 

La classe bitmap di C++Builder, usata per rappresenta immagini bitmap in risorse e 
file, puo operare anch'essa come un'immagine fuori schermo. 

I due aspetti principali relativi alle operazioni con bitmap fuori schermo sono: 

• Creazione e gestione di bitmap fuori schermo. 

• Copia di immagini bitmap. 

Creazione e gestione di bitmap fuori schermo 



Quando si crea un'immagine grafica complessa, e consigliabile non disegnarla 
direttamente sul canvas che appare sullo schermo. Anziche disegnare sul canvas 
della scheda o del controllo, si puo costruire un oggetto bitmap, disegnare sul canvas 
dell'oggetto, e infine copiare l'immagine cosi completata nel canvas sullo schermo. 
L'uso piu comune di una bitmap fuori schermo avviene nel metodo Paint di un 
controllo grafico. 

Per un esempio di come disegnare un'immagine complessa su una bitmap fuori 
schermo, esaminare il codice sorgente del controllo Gauge presente nella pagina 
Samples della Component palette. II controllo gauge traccia le varie forme e il testo 
su una bitmap fuori schermo prima di copiarle sullo schermo. II codice sorgente del 
controllo e reperibile nel file Cgauges.cpp presente nella subdirectory Examples \ 
Controls \ Source. 
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Copia di immagini bitmap 



C++Builder consente di usare quattro modi differenti per copiare le immagini da un 
canvas all'altro. A seconda dell'effetto che si vuole ottenere, occorre chiamare un 
metodo differente. 

La Tabella 50.2 riassume i metodi per la copia di immagini negli oggetti canvas. 
Tabella 50.2 Metodi per la copia di immagini 



Per creare questo effetto 

Copiare un intero grafico. 

Copiare e ridimensionare un grafico. 

Copiare parte di un canvas. 

Copiare una bitmap con operazioni raster. 

Copiare un grafico piu volte affiancandolo 
fino a riempire un'area. 



Chiamare questo metodo 

Draw 

StretchDraw 
CopyRect 
BrushCopy (VCL) 
TiledDraw(CLX) 



Risposta alle modifiche 



Tutti gli oggetti grand, incluso i canvas e i relativi oggetti posseduti (penne, pennelli, 
e font), possiedono eventi predefiniti per rispondere alle modifiche dell'oggetto. 
Usando questi eventi, si pud fare in modo che i componenti (o le applicazioni che li 
usano) rispondano alle modifiche ridisegnando le proprie immagini. 

Rispondere alle modifiche negli oggetti grafici e particolarmente importante se li si 
rende pubblici come parte dell'interfaccia di progettazione dei componenti. L'unico 
modo per assicurarsi che l'aspetto del componente in fase di progetto coincida con le 
proprieta impostate nell' Object Inspector e quello di rispondere alle modifiche degli 
oggetti. 

Per rispondere ai cambiamenti in un oggetto grafico, assegnare un metodo all'evento 
OnChange della classe. 

II componente shape rende pubbliche le proprieta che rappresentano la penna e il 
pennello usati per disegnarne il contorno. II costruttore del componente assegna un 
metodo all'evento OnChange di ciascuno di essi, facendo in modo che il componente 
si ridisegni automaticamente a video nel caso vengano modificati la penna o il 
pennello. Sebbene il componente shape sia scritto in Object Pascal, quella che segue e 
la traduzione in linguaggio C++ del componente shape con un nuovo nome, 
TMyShape. 

Questa e la dichiarazione della classe nel file header: 

class PACKAGE TMyShape : public TGraphicControl 
{ 

private: 

protected: 

public: 

virtual fastcall TMyShape (TComponent* Owner); 

__published: 
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TPen *FPen; 
TBrush *FBrush; 

void __fastcall StyleChanged(TObject * Sender ) ; 

}; 

Questo e il codice nel file .CPP: 

__fastcall TMyShape: :TMyShape(TComponent* Owner) 
: TGraphicControl (Owner) 

{ 

Width = 65; 
Height = 65; 
FPen = new TPen; 
FPen->OnChange = StyleChanged; 
FBrush = new TBrush; 
FBrush->OnChange = StyleChanged; 

} 

void __fastcall TMyShape: : StyleChanged (TObject *Sender) 

{ 

Invalidated ; 

} 
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Gestione dei messaggi e delle 

notifiche di sistema 

I componenti spesso devono rispondere alle notifiche dal sistema operativo 
sottostante. II sistema operativo informa l'applicazione di accadimenti, come ad 
esempio, cio che fa l'utente con il mouse e con la tastiera. Anche alcuni controlli 
generano delle notifiche, come i risultati delle azioni dell'utente quale, ad esempio, la 
selezione di un elemento in una casella di riepilogo. La VCL e la CLX gestiscono gia 
la maggior parte delle comuni notifiche. E comunque possibile che vi sia la necessita 
di scrivere un codice proprio per gestire tali notificazioni. 

Nella VCL, le notifiche arrivano sotto forma di messages. Questi messaggi possono 
provenire da una qualsiasi sorgente, inclusi Windows, i componenti della VCL e i 
componenti che sono statidefiniti. Vi sono tre aspetti da considerare quando si opera 
con i messaggi: 

• II sistema di gestione dei messaggi 

• Modifica della gestione dei messaggi 

• Creazione di nuovi gestori di messaggio 

In CLX, le notifiche arrivano sotto forma di segnali e di eventi di sistema invece che 
sotto forma di messaggi di Windows. Per i dettagli su come operare con le notifiche 
di sistema nella CLX, vedere "Risposta alle notifiche di sistema utilizzando la CLX" a 
pagina 51-11. 

II sistema di gestione dei messaggi 



Tutte le classi della VCL dispongono di un meccanismo incorporato per la gestione 
dei messaggi, cosiddetti metodi di gestione dei messaggi o gestori dei messaggi. 
L'idea fondamentale nella gestione dei messaggi e che le classi ricevono messaggi di 
qualche tipo e li distribuiscono, chiamando un determinato metodo appartenente a 
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un gruppo, a seconda del messaggio ricevuto.Se non esiste nessun metodo specifico 
per un determinate) messaggio, viene richiamato un gestore predefinito. 

Lo schema che segue mostra come funziona il meccanismo di smistamento dei 
messaggi: 



Event - 



MainWndProc 



WndProc 



► Dispatch 



Handler 



La Visual Component Library definisce un sistema di smistamento dei messaggi che 
trasforma tutti i messaggi di Windows (compresi quelli definiti dall'utente), diretti a 
una classe particolare, in chiamate a metodi. Non sara mai necessario modificare il 
meccanismo di smistamento dei messaggi. Tutto cio che occorre fare e creare metodi 
per gestire i messaggi. Per maggiori informazioni consultare la sezione 
"Dichiarazione di un nuovo metodo di gestione messaggi" a pagina 51-8. 



Cosa contiene un messaggio di Windows? 



Un messaggio di Windows puo essere immaginato come una struttura di dati che 
contiene diversi membri dati utili. II piu importante di questi e rappresentato da un 
valore di tipo integer che identifica il messaggio. Windows definisce molti messaggi, 
e il file MESSAGES.HPP ne dichiara tutti gli identificatori. 

I programmatori Windows sono soliti lavorare con le definizioni di Windows che 
identificano un messaggio, come, ad esempio, WMjCOMMAND o WM_PAINT. Un 
programma Windows tradizionale contiene una procedura di finestra che serve 
come callback per i messaggi generati dal sistema. In questa procedura di finestra 
esiste solitamente un'istruzione switch piuttosto corposa con varie istruzioni case, 
una per ciascun messaggio che questa finestra e in grado di gestire. 

A questa procedura per finestra vengono passate ulteriori informazioni utili 
mediante due parametri, ivParam e IParam, per "word parameter" e "long parameter" . 
Spesso, ogni parametro contiene piu di una porzione di informazione ed e necessario 
estrarre la porzione rilevante mediante le macro di Windows, quali LOWORD e 
HIWORD. Per esempio, chiamando HIWORD( IParam ) si ricava la word alta di 
questo parametro. 

Originariamente, i programmatori Windows erano costretti a ricordare o a cercare 
nelle API di Windows quali informazioni erano contenute in ogni parametro. 
Windows ha recentemente implementato i "message crackers" per semplificare la 
sintassi relativa alia gestione dei messaggi Windows e dei parametri associati. Con i 
"message crackers," anziche utilizzare una vasta istruzione switch che analizza tutte le 
informazioni contenute nei parametri, si puo semplicemente associare al messaggio 
una funzione di gestione. Se si include WINDOWSX.H in un programma Windows 
standard, risulta disponibile la macro HANDLE_MSG e si puo scrivere un codice 
come questo: 

void MyKeyDownHandlerf HWND hwnd, UINT nVirtKey, BOOL fDown, int CRepeat, UINT flags ) 
{ 

} 



LRESULT MyWndProc( HWND hwnd, UINT Message, WPARAM wParam, LPARAM IParam ) 
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{ 

switch) Message ) 
{ 

HANDLE_MSG ( hwnd, WM_KEYDOWN , MyKeyDownHandler ) ; 

} 

L'uso di questo stile di frantumazione dei messaggi rende piu palese il fatto che i 
messaggi vengono smistati a particolari gestori. Inoltre, si possono dare nomi 
significativi alia lista dei parametri per le proprie funzioni di gestione. In questo 
modo e piu facile comprendere una funzione che accetta un parametro chiamato 
nVirtKey, il quale rappresenta il valore di wParam in un messaggio WM_KEYDOWN. 

Smistamento dei messaggi 



Quando un'applicazione crea una finestra, essa registra nel kernel di Windows una 
procedura di finestra. La procedura di finestra e la routine che gestisce i messaggi per 
la finestra. Tradizionalmente, nella procedura di finestra c'e un'istruzione switch 
piuttosto corposa che contiene gli elementi di ciascun messaggio che dovra essere 
gestito dalla finestra. E bene ricordare che il termine "finestra", in questa accezione, 
pud far riferimento a qualsiasi cosa presente sullo schermo: ogni finestra, ogni 
controllo e cosi via. Ogni volta che si crea un nuovo tipo di finestra, e necessario 
creare una procedura di finestra completa. 

La VCL semplifica lo smistamento dei messaggi in vari modi: 

• Ciascun componente eredita un sistema completo per lo smistamento dei 
messaggi. 

• II sistema di smistamento ha una gestione standard. II programmatore deve 
definire solo gli handle per i messaggi ai quali va data una risposta particolare. 

• E possibile modificare una piccola parte della gestione dei messaggi e affidarsi ai 
metodi ereditati per la maggior parte dell'elaborazione. 

II maggior vantaggio di questo sistema di smistamento messaggi risiede nella 
possibility di inviare in tutta sicurezza qualsiasi messaggio a qualsiasi componente in 
qualsiasi momento. Se il componente non ha un gestore per quel messaggio, e la 
gestione predefinita che se ne occupa, di soli to ignorando il messaggio. 

II flusso dei messaggi 

La VCL registra un metodo di nome MainWndProc come procedura per finestra per 
ciascun tipo di componente presente in un'applicazione. MainWndProc contiene un 
blocco per la gestione delle eccezioni, che passa la struttura del messaggio da 
Windows a un metodo virtuale di nome WndProc e che gestisce qualunque eccezione 
chiamando il metodo HandleException della classe applicazione. 

MainWndProc e un metodo non virtuale che non contiene alcuna gestione per nessun 
particolare messaggio. Le personalizzazioni avvengono in WndProc, dal momento 
che ogni tipo di componente puo ridefinire il metodo per soddisfare le proprie 
particolari necessita. 
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I metodi WndProc controllano tutte le condizioni particolari che possono influenzare 
l'elaborazione "catturando" i messaggi non desiderati. Per esempio, mentre vengono 
trascinati, i componenti ignorano gli eventi di tastiera, pertanto il metodo WndProc di 
TWinControl lascia passare gli eventi di tastiera solo se il componente non viene 
trascinato. Infine, WndProc chiama Dispatch, un metodo non virtuale ereditato da 
TObject, che stabilisce quale metodo chiamare per gestire il messaggio. 

Dispatch utilizza il membro dati Msg della struttura del messaggio per stabilire come 
smistare un particolare messaggio. Se il componente definisce un gestore per quel 
particolare messaggio, Dispatch chiama il metodo. Se il componente non definisce un 
gestore per quel messaggio, Dispatch chiama DefaultHandler. 

Modifica della gestione dei messaggi 



Prima di cambiare la gestione dei messaggi dei propri componenti, accertarsi che 
questo sia veramente do che si desidera. La VCL traduce la maggior parte dei 
messaggi Windows in eventi che possono essere gestiti sia da chi scrive componenti 
sia da chi li utilizza. Invece di cambiare il comportamento della gestione dei 
messaggi, e piu probabile che occorra modificare il comportamento della gestione 
dell'evento. 

Per cambiare la gestione dei messaggi nei componenti della VCL, si ridefinisce il 
metodo che gestisce il messaggio. In determinate circostanze, si puo anche impedire 
che un componente gestisca un messaggio, intercettando il messaggio stesso. 

Ridefinizione del metodo di gestione 



Per cambiare il modo in cui un componente gestisce un particolare messaggio, si 
deve ridefinire il metodo che lo gestisce. Se il componente non gestisce gia quel 
particolare messaggio, diventa necessario dichiarare un nuovo metodo per la 
gestione. 

Per ridefinire il metodo di gestione di un messaggio, 

1 Dichiarare nella parte protetta della dichiarazione del componente un nuovo 
metodo nel proprio componente con lo stesso nome del metodo che si vuole 
ridefinire. 

Correlare il metodo al messaggio che esso ridefinisce utilizzando tre macro. 
Le macro assumono questa forma: 

BEGIN J4ESSAGEJ4AP 
MESSAGE_HANDLER (parameter!., parameter2, parameteri) 

ENDJ4ESSAGEJ4AP 

Parameterl e l'indice del messaggio definito da Windows, parameter! e il tipo di 
struttura del messaggio, e parameter?) e il nome del metodo del messaggio. 

E possibile inserire un numero qualunque di macro MESSAGE_HANDLER tra le 
macro BEGIN _MES SAGE _MAP e END_MESSAGE_MAP. 
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Per esempio, per ridefinire la gestione del componente del messaggio WM_PAINT, si 
deve ridichiarare il metodo WMPaint, e con le tre macro si deve correlare il metodo al 
messaggio WM_PAINT: 

class PACKAGE TMyComponent : public TComponent 

{ 

protected: 

void __fastcall WMPaint (TWMPaint* Message); 

BEGIN J4ESSAGEJ4AP 

MESSAGE_HANDLER(WM_ PAINT, TWMPaint, WMPaint) 
END_MESSAGE_MAP (TComponent ) 
}; 

Uso dei parametri del messagio 



Una volta all'interno del metodo di gestione dei messaggi, il componente ha accesso 
a tutti i parametri della struttura dei messaggi. Poiche il parametro passato al gestore 
di messaggi e un puntatore, il gestore, se necessario, puo modificare il valore dei 
parametri. L'unico parametro che cambia frequentemente e il valore di ritorno del 
messaggio: il valore restituito dalla chiamata a SendMessage che invia il messaggio. 

Poiche nel metodo di gestione dei messaggi il tipo del parametro Message varia in 
funzione del messaggio gestito, per informazioni sui nomi e sul significato dei singoli 
parametri e necessario fare riferimento alia documentazione relativa ai messaggi di 
Windows. Se per qualsiasi ragione fosse necessario fare riferimento ai parametri del 
messaggio usando la vecchia denominazione (WParam, LParam e cosi via), e possibile 
effettuare la conversione di tipo da Message al tipo generico TMessage, che utilizza 
quei nomi di parametri. 

Intercettazione dei messaggi 



In alcune circostanze potrebbe risultare preferibile che i componenti ignorino i 
messaggi. Vale a dire, si potrebbe impedire che il componente smisti il messaggio al 
proprio gestore. Per intercettare il messaggio, occorre ridefinire il metodo virtuale 
WndProc . 

Per i componenti della VCL, il metodo WndProc analizza i messaggi prima di passarli 
al metodo Dispatch, il quale, a sua volta, determina quale metodo usare per gestire il 
messaggio. Se si ridefinisce WndProc, il componente ha la possibility di filtrare i 
messaggi prima di smistarli. La ridefinizione di WndProc di un controllo derivato da 
TWinControl assomiglia all'esempio seguente: 

void __fastcall TMyControl: :WndProc (TMessageS Message) 

{ 

// tests to determine whether to continue processing 
if (Message. Msg != WM_LBUTT0ND0WN) 
TWinControl: : WndProc (Message) ; 

} 
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II componente TControl definisce l'intera serie di messaggi relativi al mouse e li filtra 
se un utente esegue operazioni di "drag and drop" con i controlli. Ridefinendo 
WndProc, questo compito viene facilitato in due modi: 

• E possibile filtrare gruppi di messaggi anziche specificare i gestori per ciascuno di 
essi. 

• E possibile impedire completamente che il messaggio venga smistato, in modo che 
i gestori non siano mai chiamati. 

Qui di seguito viene riportata una parte del metodo WndProc per TControl cosi come 
e stata implementata nella VCL in Object Pascal: 

procedure TControl. WndProc (var Message: TMessage); 
begin 

if (Message. Msg >= WM_M0USEFIRST) and (Message. Msg <= WM_MOUSELAST) then 
if Dragging then { handle dragging specially } 

DragMouseMsg(TWMMouse (Message) ) 
else 

I { handle others normally } 

end; 

: { otherwise process normally } 

end; 

Creazione di nuovi gestori di messaggio 



Poiche la VCL mette a disposizione i gestori per i messaggi piu comuni, il momento 
piu probabile in cui sara necessario creare nuovi gestori di messaggi, sara quando si 
definiranno i propri messaggi. Lavorare con messaggi definiti dall'utente presenta 
tre aspetti: 

• Definizione di un proprio messaggio. 

• Dichiarazione di un nuovo metodo di gestione messaggi. 

• Invio di messaggi. 

Definizione di un proprio messaggio 



Una gran quantita di componenti standard definisce messaggi per uso interne II 
motivo piu comune che induce alia definizione di messaggi e la necessita di 
trasmettere informazioni non coperte dai messaggi standard e di notificare i 
cambiamenti di stato. E possibile definire i propri messaggi nella VCL. 

La definizione di un messaggio e un processo in due fasi. Queste sono: 

1 Dichiarazione di un identificatore di messaggio. 

2 Dichiarazione di un tipo di struttura di messaggio. 
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Dichiarazione di un identificatore di messaggio 

Un identificatore di messaggio e una costante di tipo integer. Windows si riserva i 
numeri inferiori a 1.024 per proprio uso; pertanto se si vuole dichiarare un messaggio 
personalizzato, e necessario utilizzare un valore piu alto. 

La costante WM_APP rappresenta il numero iniziale per i messaggi definiti 
dall'utente. Quando si definiscono gli identificatori di messaggio, si deve utilizzare 
come numero base WM_APP. 

E bene tenere presente che alcuni controlli standard di Windows utilizzano messaggi 
nell'intervallo definito dall'utente. Questi includono le caselle di riepilogo, le caselle 
di testo, le caselle combinate e i pulsanti di comando. Se si vuole derivare un 
componente da uno di questi elementi e si vuole definire per esso un nuovo 
messaggio, bisogna ricordarsi di controllare il file MESS AGES. HPP per vedere quali 
messaggi Windows ha gia definito per quel controllo. 

II codice riportato di seguito mostra due messaggi definiti dall'utente. 

#define MY_MYFIRSTMESSAGE (WM_APP + 400) 
♦define MYJfYSECONDMESSAGE (WM_APP + 401) 



Dichiarazione di un tipo di struttura di messaggio 

Se si vogliono assegnare nomi significativi ai parametri del messaggio, si deve 
dichiarare per quel messaggio un tipo message structure. Message structure e il tipo di 
parametro passato al metodo di gestione messaggi. Se non si utilizzano i parametri di 
messaggio, o se si vuole utilizzare la notazione vecchio stile (wParam, IParam, ecc), si 
puo utilizzare TMessage, la struttura di messaggio predefinita. 

Per dichiarare un tipo message-structure e necessario seguire queste convenzioni: 

1 Assegnare un nome al tipo structure dopo il messaggio, anteponendo una T. 

2 Assegnare al primo membro dati nella struttura il nome Msg, di tipo TMsgParam. 

3 Definire i successivi due byte in modo che corrispondano al parametro Word, e gli 
altri due byte successivi come non utilizzati. 

Oppure 

Definire i successivi quattro byte in modo che corrispondano al parametro Longint. 

4 Aggiungere un membro dati finale di nome Result, di tipo Longint. 

Ad esempio, questa e la struttura per tutti i messaggi del mouse, TWMKey: 

struct TWMKey 
{ 

Cardinal Msg; // first parameter is the message ID 

Word CharCode; // this is the first wParam 

Word Unused; 

Longint KeyData; // this is the IParam 

Longint Result; // this is the result data member 

}; 
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Dichiarazione di un nuovo metodo di gestione messaggi 



In due casi diventa necessario dichiarare un nuovo metodo di gestione messaggi: 

• Quando il componente deve gestire un messaggio di Windows che non e gia 
gestito da uno dei componenti standard. 

• Quando e stato definito un messaggio personalizzato che verra usato dai propri 
componenti. 

Per dichiarare un metodo di gestione messaggi, occorre: 

1 Dichiarare il metodo nella sezione protected della dichiarazione della classe del 
componente utilizzando le macro BEGIN_MESSAGE_MAP ... 
END_MESSAGE_MAP. 

2 Assicurarsi che il metodo restituisca un void. 

3 Assegnare un nome al metodo dopo il messaggio da esso gestito, ma senza il 
carattere di sottolineatura. 

4 Passare un puntatore di nome Message di tipo message-structure. 

5 Mappare il metodo al messaggio utilizzando le macro. 

6 All'interno dell'implementazione del metodo del messaggio, scrivere il codice per 
qualsiasi gestione particolare relativa al componente. 

7 Chiamare il gestore del messaggio ereditato. 

Ecco, per esempio, la dichiarazione di un gestore di messaggi per un messaggio 
definito dall'utente di nome CMjCHANGECOLOR. 

♦define CM_CHANGEC0L0R (WM_APP + 400) 

class TMyControl : public TControl 

{ 

protected: 

void __fastcall CMChangeColor (TMessage Message); 

BEGIN J4ESSAGEJ4AP 

MESSAGE_HANDLER (CM_CHANGEC0L0R, TMessage, CMChangeColor) 
ENDUES SAGE_MAP ( TCon t ro 1 ) 

}; 

void __fastcall TMyControl: : CMChangeColor (TMessage Message) 

{ 

Color = Message. LParam; // set color from long parameter 

TControl: : CMChangeColor (Message) ; // call the inherited message handler 

} 

Invio di messaggi 



Di solito, un'applicazione manda un messaggio per inviare notifiche di modifiche 
alio stato o per irasmettere informazioni. II componente puo trasmettere messaggi a 
tutti i controlli in una scheda, inviare messaggi a un particolare controllo (o 
all'applicazione stessa) o anche inviare messaggi a se stesso. 
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Creazione di nuovi gestori di messaggio 

Esistono vari modi per inviare un messaggio Windows. II metodo utilizzato dipende 
dal tipo di messaggio inviato. I seguenti argomenti descrivono i diversi modi per 
inviare messaggi Windows. 

Trasmissione di un messaggio a tutti i controlli in una scheda 

Quando il componente modifica delle impostazioni globali che influiscono su tutti i 
controlli in una scheda o in altro contenitore, si potrebbe volere inviare un messaggio 
a quei controlli in modo che essi si possano aggiornare adeguatamente. Non tutti i 
controlli potrebbero avere bisogno di rispondere alia notifica, ma trasmettendo il 
messaggio, e possibile informare tutti i controlli che sanno come rispondere e 
permettere agli altri controlli di ignorare il messaggio. 

Per trasmettere un messaggio a tutti i controlli in un altro controllo, utilizzare il 
metodo Broadcast. Prima di trasmettere un messaggio, si riempie una struttura di 
messaggio con le informazioni che si desidera comunicare. (Per informazioni sulle 
strutture dei messaggi, vedere "Dichiarazione di un tipo di struttura di messaggio" a 
pagina 51-7). 

TMessage Msg; 

Msg. Msg = MY_MYCUSTOMMESSAGE ; 
Msg.WParam = 0; 
Msg.LParam = (int) (this); 
Msg. Result = 0; 

Quindi, passare questa struttura di messaggio al genitore di tutti i controlli a cui si 
desidera inviare la notifica. Questi puo essere un qualsiasi controllo 
nell'applicazione. Ad esempio, puo essere il genitore del controllo che si sta 
scrivendo: 

Parent->Broadcast (Msg) ; 
Puo essere la scheda che contiene il controllo: 

GetParentForm(this) ->Broadcast (Msg) ; 
Puo essere la scheda attiva: 

Screen->ActiveForm->Broadcast (Msg) ; 

Possono anche essere tutte le schede nell'applicazione: 

for (int i = 0; i < Screen->FormCount ; i++) 
Screen->Forms [i] ->Broadcast (Msg) ; 

Chiamata diretta del gestore del messaggio di un controllo 

Talvolta c'e solo un singolo controllo che deve rispondere al messaggio. Se si conosce 
il controllo che dovrebbe ricevere il messaggio, il modo piu semplice e diretto per 
inviare il messaggio consiste nel chiamare il metodo Perform del controllo. 

Vi sono due motivi principali per cui si chiama il metodo Perform di un controllo: 

• Si desidera innescare la stessa risposta che il controllo da ad un messaggio 

standard Windows (o ad un altro). Ad esempio, quando un controllo griglia riceve 
un messaggio di pressione tasti, crea un controllo inline di edit e quindi invia il 
messaggio di pressione tasti al controllo di edit. 
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• II controllo a cui si desidera inviare la notifica potrebbe essere noto, ma si potrebbe 
non sapere che tipo di controllo e. Poiche non si conosce il tipo del controllo di 
destinazione, non si pud utilizzare nessuno dei suoi metodi specializzati, ma 
poiche tutti i controlli hanno la capacita di gestire i messaggi e sempre possibile 
inviare un messaggio. Se il controllo ha un gestore di messaggio per il messaggio 
che viene inviato, rispondera adeguatamente. Altrimenti, ignorera il messaggio 
inviato e restituira 0. 

Per chiamare il metodo Perform, non e necessario creare una struttura di messaggio. E 
necessario solo passare come parametri l'identificativo del messaggio, WParam e 
LParam. Perform restituisce il risultato del messaggio. 

Invio di un messaggio utilizzando la coda dei messaggi Windows 

In un'applicazione multithread non e sufficiente chiamare il metodo Perform perche il 
controllo di destinazione e in un thread diverso da quello che e in esecuzione. 
Tuttavia, utilizzando la coda dei messaggi Windows, e possibile comunicare in tutta 
sicurezza con altri thread. La gestione dei messaggi si verifica sempre nel thread VCL 
principale, ma e possibile mandare un messaggio mediante la coda dei messaggi 
Windows da un qualsiasi thread nell'applicazione. Una chiamata a SendMessage e 
sincrona. Cioe, SendMessage non ritorna finche il controllo di destinazione non ha 
gestito il messaggio, anche se e in un altro thread. 

Utilizzare la chiamata API Windows, SendMessage, per inviare un messaggio a un 
controllo utilizzando la coda dei messaggi Windows. SendMessage accetta gli stessi 
parametri del metodo Perform, salvo la necessita di identificare il controllo di 
destinazione passando il suo handle Window. Cosi, invece di scrivere 

MsgResult = TargetControl->Perform(MY_MYMESSAGE, 0, 0); 
si dovrebbe scrivere 

MsgResult = SendMessage(TargetControl->Handle, MYMESSAGE, 0, 0); 

Per maggiori informazioni sulla funzione di SendMessage, consultare la 
documentazione MSDN di Microsoft. Per ulteriori informazioni sulla scrittura di piu 
thread che possono essere contemporaneamente in esecuzione, vedere 
"Coordinamento dei thread" on pagina 11-7. 

Invio di un messaggio che non viene eseguito immediatamente 

A volte si potrebbe volere inviare un messaggio ma non si sa se sia sicuro che il 
destinatario del messaggio lo esegua immediatamente. Ad esempio, se il codice che 
invia un messaggio viene chiamato da un gestore di evento sul controllo di 
destinazione, si potrebbe volere essere certi che l'esecuzione del gestore di evento sia 
terminata prima che il controllo esegua il messaggio. E possibile gestire questa 
situazione a patto che non sia necessario conoscere il risultato del messaggio. 

Utilizzare la chiamata API Windows, PostMessage, per inviare un messaggio a un 
controllo e al contempo consentirgli di attendere di aver terminato di gestire tutti gli 
altri messaggi prima di gestire il vostro. PostMessage accetta esattamente gli stessi 
parametri di SendMessage. 
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Per maggiori informazioni sulla funzione di PostMessage, consultare la 
documentazione MSDN di Microsoft. 

Risposta alle notifiche di sistema utilizzando la CLX 



Quando si utilizza Windows, il sistema operativo invia le notifiche direttamente 
all'applicazione e ai controlli che essa contiene utilizzando messaggi Windows. 
Questo approccio, tuttavia, non e appropriato per la CLX, in quanto la CLX e una 
libreria multipiattaforma e i messaggi Windows non sono utilizzati in Linux. Per 
rispondere alle notifiche di sistema CLX utilizza invece una modalita indipendente 
dalla piattaforma 

In CLX, la modalita analoga ai messaggi Windows e un sistema di segnali 
provenienti dallo strato del widget sottostante. Mentre nella VCL i messaggi 
Windows possono avere origine o dal sistema operativo o dai controlli Windows 
nativi che la VCL avvolge, lo strato del widget utilizzato dalla CLX fa a una 
distinzione fra questi due. Se la notifica ha origine da un widget, e detta un segnale. 
Se la notifica ha origine dal sistema operativo, e detta evento di sistema. Lo strato del 
widget comunica ai componenti CLX gli eventi di sistema come segnali di tipo evento. 



Risposta ai segnali 



Lo strato del widget sottostante emette una gamma di segnali, ognuno dei quali 
rappresenta un tipo diverso di notifica. Questi segnali includono oltre agli eventi di 
sistema (il segnale di evento) anche le notifiche specifiche del widget che le ha 
generate. Ad esempio, tutti i widget quando vengono liberati generano un segnale 
destroyed, i widget trackbar generano un segnale valueChanged, i controlli header 
generano un segnale sectiondicked, e cosi via. 

Ogni componente CLX risponde ai segnali provenienti dal proprio widget 
sottostante assegnando un metodo come gestore del segnale. Cio viene fatto 
utilizzando un oggetto hook speciale, associato al widget sottostante. L'oggetto hook 
e un oggetto leggero che in realta e solo una raccolta di puntatori a metodo, ognuno 
dei quali e specifico per un particolare segnale. Quando un metodo del componente 
CLX e stato assegnato all'oggetto hook come gestore di un segnale specifico, ogni 
volta che il widget genera il segnale specifico, viene chiamato il metodo sul 
componente CLX. Questo comportamento e illustrato nella Figura 51.1. 

Figura 51.1 Instradamento del segnale 
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I metodi di ogni oggetto hook sono dichiarati nella unit Qt. Controllare il file qt.hpp 
per vedere i metodi disponibili per un determinate) oggetto hook. I metodi sono 
semplificati in routine globali con nomi che riflettono l'oggetto hook a cui essi 
appartengono. Ad esempio, tutti i metodi sull'oggetto hook associato al widget 
applicazione (Q Application) iniziano ' QApplication_hook'. Questa semplificazione 
e necessaria in modo che l'oggetto CLX di Object Pascal possa accedere ai metodi 
dell'oggetto hook di C++. 

Assegnazione dei gestori di segnale custom 

Molti controlli CLX assegnano gia metodi per gestire segnali dal widget sottostante. 
Di solito, questi metodi sono privati e non virtuali. Pertanto, se si desidera scrivere 
un proprio metodo per rispondere a un segnale, e necessario assegnare il metodo 
all'oggetto hook associato al widget. Per fare cio, si deve ridefinire il metodo 

HookEvents. 

Se il segnale a cui si desidera rispondere e una notifica di un evento di sistema, non si 
deve utilizzare una ridefinizione del metodo HookEvents. Per i dettagli su come 
rispondere agli eventi di sistema, vedere "Risposta a eventi di sistema" nel prosieguo 
del capitolo. 

Nella ridefinizione del metodo HookEvents, dichiarare una variabile di tipo TMethod. 
Quindi, per ogni metodo che si desidera assegnare come gestore di segnale 
all'oggetto hook, fare quanta segue: 

1 Inizializzare la variabile del tipo TMethod per rappresentare un gestore di metodo 
per il segnale. 

2 Assegnare questa variabile all'oggetto hook. E possibile accedere all'oggetto hook 
utilizzando la proprieta Hooks che il componente eredita da THandleComponent o 
TWidgetControl. 

Nella ridefinizione, chiamare sempre il metodo ereditato HookEvents in modo da 
connettere anche i gestori di segnale assegnati dalle classi di base. 

II codice seguente e una traduzione del metodo HookEvents di TTrackBar. Illustra 
come ridefinire il metodo HookEvents per aggiungere dei gestori custom di segnale. 

virtual void fastcall TTrackBar: : HookEvents (void) 

{ 

TMethod Method; 

// initialize Method to represent a handler for the QSlider valueChanged signal 
// ValueChangedHook is a method of TTrackBar that responds to the signal. 
QSlider_valueChanged_Event (Method) = @ValueChangedHook; 
// Assign Method to the hook object. Note that you can cast Hooks to the 
// type of hook object associated with the underlying widget. 
QSlider_hook_hook_valueChanged(dynamic_cast <QSlider_hookH> (Hooks) , Method) ; 
// Repeat the process for the sliderMoved event: 
QSlider_sliderMoved_Event (Method) := @ValueChangedHook; 
QSlider_hook_hook_valueChanged(dynamic_cast <QSlider_hookH> (Hooks) , Method) ; 
// Call the inherited method so that inherited signal handlers are hooked up: 
TWidgetControl :: HookEvents ( ) ; 

} 
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Risposta a eventi di sistema 



Quando lo strato del widget riceve una notifica di evento dal sistema operative 
genera uno speciale oggetto evento (QEvent o uno dei suoi discendenti) per 
rappresentare l'evento. L'oggetto evento contiene informazioni a sola lettura 
sull'evento che si e verificato. II tipo dell'oggetto evento indica il tipo di evento che si 
e verificato. 

Lo strato del widget notifica al componente CLX gli eventi di sistema utilizzando uno 
speciale segnale di tipo evento. Esso passa l'oggetto QEvent al gestore di segnale 
dell'evento. L'elaborazione del segnale di evento e un po' piu complicata rispetto 
all'elaborazione di altri segnali in quanto arriva prima all'oggetto applicazione. Cio 
significa che un'applicazione ha due opportunity per rispondere a un evento di 
sistema: una volta a livello dell'applicazione (T 'Application) e una volta a livello del 
singolo componente (il discendente TWidgetControl o THandleComponent). Tutte 
queste classi {T Application, TWidgetControl e THandleComponent) assegnano gia dallo 
strato del widget un gestore di segnale per il segnale evento. Cioe, tutti gli eventi di 
sistema vengono indirizzati automaticamente al metodo EventFilter, che ha un ruolo 
simile al metodo WndProc dei controlli VCL. La gestione degli eventi di sistema e 
illustrata nella Figura 51.2. 

Figura 51 .2 Instradamento dell'evento di sistema 
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EventFilter gestisce la maggior parte delle notifiche di sistema comunemente 
utilizzate, traducendole negli eventi che sono introdotti dalle classi di base del 
componente. Cosi, ad esempio, il metodo EventFilter di TWidgetControl risponde agli 
eventi del mouse (QMouseEvent) generando gli eventi OnMouseDown, OnMouseMove 
e OnMousellp, agli eventi di tastiera {QKeyEvent) generando gli eventi OnKeyDoivn, 
OnKeyPress, OnKeyString e OnKeyllp, e cosi via. 



Eventi comunemente utilizzati 

II metodo EventFilter di TWidgetControl gestisce molte delle comuni notifiche di 
sistema chiamando i metodi protetti introdotti in TControl o in TWidgetControl. La 
maggior parte di questi metodi e virtuale, in modo che sia possibile ridefinirli 
durante la scrittura di componenti e implementare le risposte agli eventi di sistema. 
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Quando si ridefiniscono questi metodi, non e necessario preoccuparsi di operare con 
l'oggetto evento o (nella maggior parte dei casi) con un qualunque altro oggetto 
presente nello strato del widget sottostante. 

Quando si desidera che il componente CLX risponda alle notifiche di sistema, e bene 
per prima cosa controllare se esiste gia un metodo protetto in grado di rispondere 
alia notifica. E possibile controllare la documentazione di TControl o di 
TWidgetControl (e qualsiasi altra classe base da cui si deriva il componente) per 
vedere se esiste un metodo protetto che risponda all'evento a cui si e interessati. La 
Tabella 51.1 elenca i metodi protetti piu comunemente utilizzati da TControl e da 
TWidgetControl che e possibile utilizzare. 

Tabella 51.1 Metodi protetti di TWidgetControl per la risposta ad eventi di sistema 
Metodo Descrizione 

BeginAutoDrag Chiamato quando 1'utente fa clic sul tasto sinistra del mouse se il contralto 
ha un DragMode impostato a dmAutomatic. 

Click Chiamato quando 1'utente rilascia il tasto del mouse sul contralto. 

DblClick Chiamato quando 1'utente fa doppio clic con il mouse sul controllo. 

DoMouseWheel Chiamato quando 1'utente gira la rotella del mouse. 

DmgOver Chiamato quando 1'utente trascina il cursore del mouse sul controllo. 

KeyDown Chiamato quando 1'utente preme un tasto mentre il controllo ha il fuoco. 

KeyPress Chiamato dopo KeyDown se KeyDown non gestisce la pressione del tasto. 

KeyString Chiamato quando 1'utente preme un tasto nel caso in cui il sistema utilizzi 

un sistema di caratteri multibyte. 

Keyllp Chiamato quando 1'utente rilascia un tasto mentre il controllo ha il fuoco. 

MouseDown Chiamato quando 1'utente fa clic sul tasto del mouse sul controllo. 

MouseMove Chiamato quando 1'utente sposta il cursore del mouse sul controllo. 

Mousellp Chiamato quando 1'utente rilascia il tasto del mouse sul controllo. 

PaintRequest Chiamato quando il sistema deve ridisegnare il controllo. 

WidgetDestroyed Chiamato quando si distrugge un widget che e alia base di un controllo. 

Nella ridefinizione, chiamare il metodo ereditato in modo che qualsiasi processo 
predefinito possa ancora rispondere ai segnali. 

Oltre ai metodi che rispondono agli eventi di sistema, i controlli includono molti 
metodi simili che hanno origine con TControl o TWidgetControl per notificare al 
controllo i diversi eventi. Benche questi non rispondano a eventi di sistema, essi 
svolgono gli stessi compiti di molti messaggi Windows che vengono inviati ai 
controlli VCL. La Tabella 51.1 elenca alcuni di questi metodi. 

Tabella 51 .2 Metodi protetti di TWidgetControl per la risposta ad eventi dai controlli 
Metodo Descrizione 

BoundsChanged Chiamato quando il controllo viene ridimensionato. 

ColorChanged Chiamato quando viene modificato il colore del controllo. 

CursorChanged Chiamato quando si modifica la forma del cursore. II cursore del mouse 

assume questa forma quando e su questo widget. 
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Tabella 51.2 Metodi 
Metodo 

EnabledChanged 

FontChanged 

PaletteChanged 

ShowHintChanged 

StyleChanged 

TabStopChanged 

TextChanged 

VisibleChanged 



protetti di TWidgetControl per la risposta ad eventi dai controlli (continua) 
Descrizione 

Chiamato quando un'applicazione modifica lo stato enabled di una finestra 
o di un controllo. 

Chiamato quando si modifica la raccolta di risorse dei font. 

Chiamato quando cambia la tavolozza del widget. 

Chiamato quando si visualizzano o si nascondono i suggerimenti di un 
controllo. 

Chiamato quando vengono cambiati gli stili GUI della finestra o del 
controllo. 

Chiamato quando si modifica la sequenza di tabulazione sulla scheda. 
Chiamato quando il testo del controllo viene modificato. 
Chiamato quando si nasconde o visualizza un controllo. 



Ridefinizione del metodo EventFilter 

Se si desidera rispondere a una notifica di evento e non c'e alcun metodo protetto per 
quell'evento che e possibile ridefinire, e possibile ridefinire lo stesso metodo 
EventFilter. Nella ridefinizione, controllare il tipo del parametro Event del metodo 
EventFilter ed eseguire la propria particolare elaborazione quando rappresenta il tipo 
di notifica a cui si desidera rispondere. E possibile evitare un'ulteriore elaborazione 
della notifica dell'evento facendo in modo che il metodo EventFilter restituisca true. 

Vedere la documentazione Qt della TrollTech per i dettagli sui vari tipi di oggetti 
QEvent. 

II codice seguente e una traduzione del metodo EventFilter di TCustomControl. Illustra 
come ottenere il tipo di evento dall'oggetto QEvent quando si ridefinisce EventFilter. 
Notare che, benche non sia visibile nell'esempio, una volta che si e identificato il tipo 
di evento, e possibile convertire il tipo dell'oggetto QEvent in un appropriato 
discendente specializzato di QEvent (come QMouseEvent). 

virtual bool __fastcall TCustomControl: :EventFilter(Qt: :Q0bjectH* Sender, Qt::QEventH* 

Event) 

{ 

bool retval = TWidgetControl: :EventFilter (Sender, Event); 

switch (QEvent_type(Event) ) 

{ 

case QEventType_Resize: 
case QEventType_FocusIn: 
case QEventType_FocusOut : 
UpdateMaskf) ; 

} 

return retval; 

} 



Generazione di eventi Qt 

Analogamente al modo in cui un controllo VCL puo definire e inviare messaggi 
Windows custom, e possibile fare in modo che il controllo CLX definisca e generi 
eventi Qt di sistema. II primo passo consiste nel definire un ID univoco per l'evento 
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(simile al modo in cui e necessario definire un ID di messaggio quando si definisce 
un messaggio Windows custom): 

static const MyEvent_ID = (int) QCLXEventType_ClxUser + 50; 

Nel codice in cui si desidera generare l'evento, si utilizza la funzione 
QCustomEvent_create (dichiarata in Qt.hpp) per creare un oggetto evento con il nuovo 
ID di evento. Un secondo parametro facoltativo permette di fornire all'oggetto 
evento un valore che e un puntatore alle informazioni che si vogliono associare 
all'evento: 

QCustomEventH *MyEvent = QCustomEvent_create (MyEvent_ID, this); 

Una volta che si e creato l'oggetto evento, e possibile registrarlo chiamando il metodo 
QApplication_postEvent: 

QApplication_postEvent (Application->Handle, MyEvent) ; 

Affinche qualsiasi componente risponda a questa notifica, e necessario solo 
ridefinirne il metodo EventFilter, controllando un tipo di evento MyEvent _ID. II 
metodo EventFilter puo acquisire i dati forniti al costruttore chiamando il metodo 
QCustomEvent_data, dichiarato in Qt.hpp. 
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Capitolo 




Come rendere disponibili i 
componenti in fase di progetto 

Questo capitolo descrive le operazioni necessarie per rendere disponibili nell'IDE i 
componenti creati. Rendere disponibile i propri componenti in fase di progetto e 
un'operazione che richiede diverse fasi: 

• Registrazione di componenti 

• Aggiunta di bitmap alia tavolozza 

• Preparazione di un file di Guida per il componente 

• Aggiunta di editor di proprieta 

• Aggiunta di editor di componenti 

• Compilazione dei componenti in package 

Non tutte queste operazioni valgono per tutti i componenti. Per esempio, se non si 
definiscono nuovi eventi o proprieta, non occorre predisporre una specifica Guida 
all'uso. Le uniche operazioni sempre necessarie sono la registrazione e la 
compilazione. 

Una volta che i propri componenti sono stati registrati e compilati in package, essi 
possono essere distribuiti ad altri sviluppatori e installati nell'IDE. Per maggiori 
informazioni sull'installazione dei packages nell'IDE, consultare il paragrafo 
"Installazione di package di componenti" a pagina 15-6. 

Registrazione di componenti 



La registrazione si fonda sulle unit e pertanto, se si creano molti componenti in una 
singola unit, e possibile registrarli tutti in una volta. 

Per registrare un componente, aggiungere una funzione Register nel file .CPP della 
unit. All'intemo della funzione Register si registrano i componenti e si determina 
dove installarli nella Component palette. 
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egistrazione di componenti 



Se si crea un componente scegliendo Component I New Component nell'IDE, il 
codice necessario per la sua registrazione viene aggiunto automaticamente. 

I passi per registrare manualmente un componente sono: 

• Dichiarazione della funzione Register 

• Scrittura della funzione Register 

Dichiarazione della funzione Register 



La registrazione comporta la scrittura nel file .CPP della unit di un'unica funzione, il 
cui nome deve essere Register. La funzione Register deve esistere all'intemo di un 
namespace. II namespace e il nome del file in cui e contenuto il componente con tutte 
le lettere in minuscolo eccetto la prima. 

II codice seguente mostra come viene implementata la funzione Register all'interno di 
un namespace. II namespace viene chiamato Newcomp, mentre il file viene chiamato 
Newcomp.CPP: 

namespace Newcomp 
{ 

void __fastcall PACKAGE Register)) 

{ 

} 

} 

Dall'intemo della funzione Register, chiamare RegisterComponents per ogni 
componente che si vuole aggiungere alia Component palette. Se la combinazione del 
file header e del file .CPP contiene diversi componenti, si puo registrarli tutti in 
un'unica operazione. La macro PACKAGE viene espansa in un'istruzione che 
consente di importare e di esportare classi. 

Scrittura della funzione Register 



All'interno della funzione Register di una unit contenente componenti, si devono 
registrare tutti i componenti che si intende aggiungere alia Component palette. Se la 
unit contiene diversi componenti, e possibile registrarli contemporaneamente. 

Per registrare un componente, chiamare la funzione RegisterComponents una volta per 
ogni pagina della Component palette alia quale si vogliono aggiungere componenti. 
RegisterComponents richiede tre cose importanti: 

1 Specifica dei componenti 

2 Specifica della pagina della tavolozza 

3 Uso della funzione RegisterComponents 

Specifica dei componenti 

All'interno della funzione Register dichiarare un array vuoto di tipo TComponentClass, 
destinato a contenere l'array di componenti da installare. La sintassi e piu o meno 
questa: 

TMetaClass classes [1] = {__classid (TNewComponent) } ; 
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Registrazione di componenti 



In questo caso, l'array di classi contiene solo un componente, ma e possibile 
aggiungervi tutti i componenti che si vogliono registrare. Per esempio, il codice 
seguente colloca due componenti nell'array: 

TMetaClass classes [2] = 

L_classid (TNewComponent) , __classid (TAnotherComponent) }; 

Un altro modo per aggiungere un componente all'array consiste nell'assegnarlo in 
un'istruzione separata. Le seguenti istruzioni aggiungono all'array gli stessi due 
componenti dell'esempio precedente: 

TMetaClass classes [2]; 

classes[0] = __classid (TNewComponent) ; 

classes [1] = __classid (TAnotherComponent) ; 

Specifica della pagina della tavolozza 

II nome della pagina della tavolozza e una AnsiString. Se il nome che viene dato alia 
pagina della tavolozza non esiste ancora, C++Builder crea una nuova pagina con 
quel nome. C++Builder registra i nomi delle pagine standard in una lista di stringhe, 
in modo che le versioni internazionali del prodotto possono chiamare le pagine nelle 
lingue locali. Se si vuole installare un componente in una pagina standard, si deve 
prima recuperare la stringa per il nome della pagina chiamando la funzione LoadStr e 
passando come argomento la costante che rappresenta la risorsa stringa per quella 
pagina, come srSystem per la pagina System. 

Uso della funzione RegisterComponents 

Dall'interno della funzione Register chiamare RegisterComponents per registrare i 
componenti nell'array delle classi. RegisterComponents e una funzione che richiede tre 
parametri: il nome di una pagina della Component palette, l'array delle classi dei 
componenti e l'indice dell'ultima voce dell'array. 

La seguente funzione Register, disponibile nel file NEWCOMP.CPP, registra un 
componente di nome TMyComponent e lo colloca in una pagina della tavolozza 
Component di nome Miscellaneous: 

namespace Newcomp 

{ 

void __fastcall PACKAGE Register!) 
{ 

TMetaClass classes [1] = {__classid (TMyComponent) } ; 
RegisterComponents ("Miscellaneous", classes, 0); 

} 

} 

Si noti che il terzo argomento della chiamata RegisterComponents e 0, che rappresenta 
l'indice dell'ultima voce dell'array delle classi (la dimensione dell'array meno 1)). 

E possibile registrare contemporaneamente diversi componenti nella stessa pagina o 
registrare i componenti in pagine differenti, come mostra il codice seguente: 

namespace Mycomps 

{ 

void __fastcall PACKAGE Register)) 
{ 
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// declares an array that holds two components 

TMetaClass classesl[2] = {__classid (TFirst) , __classid (TSecond) } ; 

// adds a new palette page with the two components in the classesl array 

RegisterComponents ( "Miscellaneous", classesl, 1); 

// declares a second array 

TMetaClass classes2 [1] ; 

// assigns a component to be the first element in the array 
classes2[0] = __ciassid (TThird) ; 

// adds the component in the classes2 array to the Samples page 
RegisterComponents ("Samples", classes2, 0); 

} 

} 

Nell'esempio vengono dichiarati due array, classesl e classes2. Nella prima chiamata 
a RegisterComponents l'array classesl ha 2 voci, per cui il terzo argomento e l'indice 
della seconda voce, che e 1. Nella seconda chiamata a RegisterComponents l'array 
classes2 ha un elemento, per cui il terzo argomento e 0. 

Aggiunta di bitmap alia tavolozza 



Ogni componente ha bisogno di una bitmap per rappresentare il componente nella 
Component palette. Se non si specifica una propria bitmap, C++Builder ne utilizza 
una predefinita. 

Poiche le tavolozze sono necessarie soltanto in fase di progetto, non occorre 
compilarle nella unit di compilazione del componente. Devono essere fornite come 
una file risorsa di Windows con lo stesso nome del file .CPP, ma con estensione .DCR 
(acronimo di Dynamic Component Resource). Questo file risorsa puo essere creato 
utilizzando l'editor Image in C++Builder. Ogni bitmap deve essere di 24 pixel 
quadrati. 

Per ogni componente che si vuole installare, occorre indicare un file bitmap della 
tavolozza, all'interno del quale si deve fornire una bitmap per ogni componente che 
si registra. L'immagine bitmap ha lo stesso nome della classe del componente. E bene 
tenere il file bitmap della tavolozza nella stessa directory in cui si trova il file 
compilato, in modo che C++Builder possa trovare le bitmap quando installa i 
componenti nella Component palette. 

Ad esempio, se si vuole creare un componente di nome TMyControl, occorre creare 
un file risorsa .DCR o .RES contenga una bitmap di nome TMYCONTROL. I nomi dei 
file risorsa possono essere scritti in lettere maiuscole o minuscole, ma per 
convenzione, sono generalmente in maiuscolo. 

Preparazione di un file di Guida per il componente 



Se si seleziona un componente standard su una scheda, o una proprieta o un evento 
nell'Object Inspector, premendo il tasto F1 si richiama la Guida relativa a quel 
determinato elemento. Creando opportuni file di Guida, si puo fornire agli 
sviluppatori lo stesso tipo di documentazione per i propri componenti. 
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Preparazione di un file di Guida per il componente 

E possibile fornire un piccolo file di guida che descriva i propri componenti. In 
questo modo il proprio file diviene parte della Guida utente del sistema C++Builder. 

Per informazioni su come comporre un file di Guida da utilizzare con i componenti, 
consultare la sezione "Creazione del file di Guida" a pagina 52-5. 

Creazione del file di Guida 



Per creare i file risorsa per la Guida di Windows (in formato rtf ), si puo utilizzare 
qualunque strumento. C++Builder include Microsoft Help Workshop che compila i 
file della Guida e mette a disposizione una Guida in linea dedicata a chi scrive tali 
file. Nella Guida in linea di Help Workshop si possono trovare informazioni 
complete sulla creazione di file di Guida. 

La creazione di file di Guida per i componenti e costituita da tre fasi: 

• Creazione delle voci 

• Come rendere sensibile al contesto la guida del componente Aggiunta di file di 
Guida al componente 

Creazione delle voci 

Per fare in modo che la Guida del proprio componente si integri completamente con 
la Guida del resto dei componenti nella libreria, osservare le seguenti convenzioni: 

1 Ogni componente deve avere un argomento della guida. 

L'argomento del componente deve mostrare in quale unit il componente e 
dichiarato e fornirne una breve descrizione. Esso deve essere collegato ad una 
finestra secondaria che descrive la posizione del componente nella gerarchia degli 
oggetti e ne elenca tutte le proprieta, gli eventi, e i metodi. Gli sviluppatori di 
applicazioni accedono a questo argomento selezionando il componente in una 
scheda e premendo F1. Per un esempio di un argomento del componente, collocare 
un componente in una scheda e premere F1. 

L'argomento del componente deve avere una nota a pie di pagina di tipo # con un 
valore univoco per identificare l'argomento. La nota a pie di pagina di tipo # serve 
al sistema della Guida per identificare in modo univoco ogni argomento. 

L'argomento del componente deve avere una nota a pie di pagina di tipo K per la 
ricerca delle parole chiave nell'Indice del sistema della Guida, che includa il nome 
della classe del componente. Per esempio, la nota a pie di pagina per la parola 
chiave relativa al componente TMemo e "TMemo." 

Deve anche avere una nota a pie di pagina di tipo $ che fornisce il titolo 
all'argomento. II titolo appare nella finestra di dialogo Topics Found, nella finestra 
di dialogo Bookmark e nella finestra History. 

2 Ogni componente deve includere i seguenti argomenti secondari per lo 
spostamento: 

• Una gerarchia di argomenti con collegamenti a ogni antenato del componente 
nella gerarchia dei componenti. 
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• Un elenco di tutte le proprieta disponibili nel componente, con collegamenti 
alle voci che descrivono quelle proprieta. 

• Un elenco di tutti gli eventi disponibili nel componente, con collegamenti alle 
voci che descrivono quegli eventi. 

• Un elenco di tutti i metodi disponibili nel componente, con collegamenti alle 
voci che descrivono quei metodi. 

Utilizzando Alinks, e possibile effettuare collegamenti alle classi, alle proprieta, ai 
metodi o agli eventi degli oggetti nella Guida del sistema C++Builder. Quando si 
effettua un collegamento ad un oggetto classe, Alink utilizza il nome di classe 
dell'oggetto, seguito da un trattino di sottolineatura e dalla stringa "object". Per 
esempio, per effettuare il collegamento all'oggetto TCustomPanel, usare il seguente 
codice: 

! AL (TCustomPanel_obj ect , 1 ) 

Quando si effettua il collegamento ad una proprieta, ad un metodo o ad un evento, 
fare precedere il nome della proprieta, del metodo o dell'evento dal nome 
dell'oggetto che lo implementa e da un trattino di sottolineatura. Per esempio, per 
collegarsi alia proprieta Text, che viene implementato da TControl, utilizzare il 
seguente codice: 

!AL(TControl_Text,l) 

Per vedere un esempio di argomento secondario di spostamento, visualizzare la 
Guida per un qualsiasi componente e fare clic sui collegamenti con etichetta 
gerarchia, proprieta, metodi o eventi. 

3 Ogni proprieta, metodo ed evento dichiarato all'interno del componente deve 
avere un proprio argomento. 

Ogni argomento di una proprieta, evento o metodo deve mostrare la dichiarazione 
dell'elemento e descriverne l'uso. Gli sviluppatori di applicazioni possono 
consultare questi argomenti evidenziando l'elemento nell'Object Inspector e 
premendo il tasto F1 oppure posizionando il cursore nel Code editor sul nome 
dell'elemento e premendo il tasto F1. Per vedere un esempio di un argomento di 
Guida relativa alle proprieta, selezionare un qualsiasi elemento nell'Object 
Inspector e premere F1. 

Gli argomenti proprieta, evento e metodo devono includere una nota a pie di 
pagina di tipo K che elenca il nome della proprieta, del metodo o dell'evento e il 
suo nome in combinazione con il nome del componente. Pertanto, la proprieta 
Text di TControl ha la seguente nota a pie di pagina di tipo K: 

Text , TControl ; TControl , Text ; Text , 

Gli argomenti proprieta, evento e metodo devono anche includere una nota a pie 
di pagina di tipo $ che indica il titolo dell'argomento, come TControl: :Text. 

Tutti questi argomenti devono avere un ID di argomento univoco, inserito come una 
nota a pie di pagina di tipo #. 

Come rendere sensibile al contesto la guida del componente 

Ogni componente, proprieta, metodo ed evento deve avere una nota a pie di pagina 
di tipo A. La nota a pie di pagina A viene utilizzata per visualizzare l'argomento 
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quando l'utente seleziona un componente e preme F1, o quando una proprieta o un 
evento viene selezionato nell'Object Inspector e l'utente preme F1. La nota a pie di 
pagina di tipo A deve rispettare alcune convenzioni per il nome: 

Se l'argomento della Guida riguarda tin componente, la nota a pie di pagina di tipo A 
e costituita da due voci separate da un punto e virgola e utilizza questa sintassi: 

ComponentClass_Object ;ComponentClass 

dove ComponentClass e il nome della classe del componente. 

Se l'argomento della Guida riguarda una proprieta o un evento, la nota a pie di 
pagina di tipo A e costituita da tre voci separate da un punto e virgola e utilizza 
questa sintassi: 

Component Class_Element; Element _Type; Element 

dove ComponentClass e il nome della classe del componente, Element e il nome della 
proprieta, del metodo o dell'evento, e Type e Property, Method o Event 

Per esempio, per una proprieta di nome Background-Color di un componente 
denominate TMyGrid, la nota a pie di pagina di tipo A e 

TMyGrid_BackgroundColor;BackgroundColor_Property;BackgroundColor 

Aggiunta di file di Guida al componente 

Per aggiungere il proprio file di Guida a C++Builder, utilizzare il programma di 
utilita OpenHelp (chiamato oh.exe) presente nella directory bin o cui si puo accedere 
dall'IDE tramite il comando Help I Customize. 

Ulteriori informazioni sull'uso di OpenHelp sono presenti nel file OpenHelp .hip, 
oltre a informazioni su come aggiungere altri file di Guida personali al sistema di 
Guida. 

Aggiunta di editor di proprieta 



L'Object Inspector fornisce funzioni predefinite di editing per tutti i tipi di proprieta. 
E possibile, comunque, indicare un editor alternativo per proprieta specifiche 
scrivendo e registrando editor di proprieta. Si possono registrare editor di proprieta 
validi soltanto per le proprieta dei componenti che si scrivono, ma si possono creare 
anche editor che si applicano a tutte le proprieta di un certo tipo. 

Al livello piu semplice un editor di proprieta puo funzionare in uno dei seguenti 
metodi o in entrambi: visualizzando e permettendo all'utente di modificare il valore 
attuale come una stringa di testo, e visualizzando una finestra di dialogo che 
permette altri tipi di modifiche. In funzione della proprieta che deve essere editata, 
puo risultare utile fornire uno o entrambi i tipi. 

La scrittura di una proprieta editor richiede queste cinque operazioni: 

1 Derivazione di una classe editor di proprieta 

2 Modifica della proprieta come testo 

3 Modifica globale della proprieta 

4 Specifica degli attributi dell'editor 
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5 Registrazione dell'editor di proprieta 

Derivazione di una classe editor di proprieta 



Sia la CLX che la VCL definiscono diversi tipi di editor di proprieta, i quali 
discendono tutti da TPropertyEditor. Quando si crea un editor di proprieta, la classe 
editor di proprieta utilizzata puo discendere direttamente da TPropertyEditor o 
indirettamente tramite una delle classi editor di proprieta descritte nella Tabella 52.1. 
Le classi nella unit DesignEditors possono essere utilizzate sia per applicazioni VCL 
sia per applicazioni CLX. Alcune classi editor di proprieta, tuttavia, forniscono 
finestre di dialogo specializzate e sono pertanto specializzate o per la VCL o per la 
CLX. Queste sono reperibili rispettivamente nelle unit VCLEditors e CLXEditors. 

La cosa assolutamente necessaria per un editor di proprieta e che discenda da 
TBasePropertyEditor e che supporti l'interfaccia IProperty. TPropertyEditor, comunque, 
off re un'implementazione predefinita dell'interf accia IProperty. 

La lista nella Tabella 52.1 non e completa. Le unit VCLEditors e CLXEditors 
definiscono anche alcuni editor di proprieta specializzati, utilizzati da proprieta 
particolari come il nome del componente. Gli editor di proprieta elencati sono quelli 
piu utilizzati per le proprieta definite dall'utente. 

Tabella 52.1 Tipi di editor di proprieta predefiniti 



Tipo Proprieta su cul opera 

TOrdinalProperty Tutti gli editor di proprieta di tipo ordinale (cioe, proprieta di tipo 
integer, carattere ed enumerato) discendenti da TOrdinalProperty. 

TlntegerProperty Tutti i tipi integer compresi quelli predefiniti e i sottointervalli definiti 
dall'utente. 

TCharProperty II tipo Char e tutti gli eventuali sottointervalli, come 'A'..'Z'. 

TEnumProperty Tutti i tipi enumerati. 

TFloatProperty Tutti i numeri in virgola mobile. 

TStringProperty AnsiStrings. 

TSetElementProperty I singoli elementi dei set, mostrati come valori booleani 

TSetProperty Tutti i set. I set non sono modificabili direttamente ma possono essere 

espansi in un elenco di proprieta elementi set. 

TClassProperty Classi. Mostra il nome della classe e permette di espanderlo per mostrare 

le proprieta rese pubbliche della classe. 

TMethodProperty Puntatori ai metodi, in modo particolare gli eventi. 

TComponentProperty Componenti nella stessa scheda. Non modifica le proprieta del 
componente ma puo puntare a un componente specifico di tipo 
compatibile. 

TColorProperty I colori dei componenti. Mostra le costanti colore se disponibili, in caso 

contrario mostra un valore esadecimale. Un elenco a discesa contiene le 
costanti colore. Un doppio clic apre una finestra di dialogo di selezione 
del colore. 
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Tabella 52.1 Tipi di editor di proprieta predefiniti 



Tipo 


Proprieta su cui opera 


TFontNameProperty 


Nomi di font. L'elenco a discesa mostra tutti i font correntemente 
installati. 


TFontProperty 


I font. Permette l'espansione delle singole proprieta font oltre a consentire 
l'accesso alia finestra di dialogo dei font. 



II seguente esempio mostra la dichiarazione di un semplice editor di proprieta di 
nome TMyPropertyEditor: 

class PACKAGE TMyPropertyEditor : public TPropertyEditor 
{ 

public : 

virtual bool fastcall AllEqual (void) ; 

virtual System: :AnsiString fastcall GetValue (void) ; 

virtual void __fastcall SetValue (const System: :AnsiString Value); 
fastcall virtual -TMyPropertyEditor (void) { } 

fastcall TMyPropertyEditor (void) : Dsgnintf : : TPropertyEditor ( ) { } 

}; 

Modifica della proprieta come testo 



Tutte le proprieta hanno bisogno di fornire una rappresentazione stringa dei loro 
valori da visualizzare nell'Object Inspector. Molte proprieta consentono, inoltre, 
all'utente di immettere un nuovo valore per la proprieta. Le classi editor di proprieta 
forniscono metodi virtuali che si possono ridefinire per effettuare la conversione tra 
la rappresentazione testuale e il valore effettivo. 

I metodi che vengono ridefiniti si chiamano GetValue e SetValue. L' editor di proprieta 
eredita anche una serie di metodi utilizzati per assegnare e leggere varie specie di 
valori, come illustrato nella Tabella 52.2. 



Tabella 52.2 Metodi per leggere e scrivere i valori delle proprieta 



Tipo della proprieta 


Metodo Get 


Metodo Set 


Numero in virgola mobile 


GetFloatValue 


SetFloatValue 


Closure (evento) 


GetMethodValue 


SetMethodValue 


Tipo ordinale 


GetOrdValue 


SetOrdValue 


Stringa 


GetStrValue 


SetStrValue 



Quando si ridefinisce un metodo GetValue, si chiama uno dei metodi Get; quando si 
ridefinisce un metodo SetValue, si chiama uno dei metodi Set. 



Visualizzazione del valore della proprieta 

II metodo GetValue dell'editor di proprieta restituisce una stringa che rappresenta il 
valore attuale della proprieta. L'Object Inspector utilizza questa stringa nella colonna 
valore della proprieta. GetValue restituisce come valore predefinito unknown". 
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Per fornire alia proprieta una rappresentazione stringa, ridefinire il metodo GetValue 
dell'editor di proprieta. 

Se la proprieta non e un valore stringa, GetValue deve convertire il valore in una 
rappresentazione stringa. 

Impostazione del valore della proprieta 

II metodo SetValue dell'editor di proprieta prende una stringa scritta dall'utente nell' 
Object Inspector, la converte nel tipo appropriate e imposta il valore della proprieta. 
Se la stringa non rappresenta un valore corretto per la proprieta, SetValue deve 
generare un'eccezione e non deve utilizzare il valore improprio. 

Per leggere i valori delle proprieta, ridefinire il metodo SetValue dell'editor di 
proprieta. 

SetValue deve convertire la stringa e convalidare il valore prima di chiamare uno dei 
metodi Set. 

Modifica globale della proprieta 



Si pud fornire opzionalmente una finestra di dialogo nella quale l'utente puo editare 
in modo visuale una proprieta. L'impiego piu comune degli editor di proprieta 
riguarda le proprieta che sono di per se delle classi. Un esempio e la proprieta Font, 
per la quale l'utente puo aprire una finestra di dialogo font per scegliere 
contemporaneamente tutti gli attributi di font. 

Per fornire una finestra di dialogo per la modifica globale delle proprieta, ridefinire il 
metodo Edit della classe dell'editor di proprieta. 

I metodi Edit usano gli stessi metodi Get e Set utilizzati nella scrittura dei metodi 
GetValue e SetValue. Infatti, un metodo Edit chiama sia un metodo Get sia un metodo 
Set. Poiche l'editor e specifico del tipo, generalmente non e'e bisogno di convertire i 
valori delle proprieta in stringhe. L'editor generalmente tratta con il valore cosi come 
lo rileva. 

Quando l'utente fa clic sul pulsante '...' vicino alle proprieta o fa doppio clic sulla 
colonna valore, l'Object Inspector chiama il metodo Edit dell'editor di proprieta. 

Durante la nuova implementazione del metodo Edit, seguire questi passi: 

1 Costruire l'editor che si sta utilizzando per la proprieta. 

2 Leggere il valore attuale e assegnarlo alia proprieta usando un metodo Get. 

3 Quando l'utente seleziona un nuovo valore, assegnare quel valore alia proprieta 
usando un metodo Set. 

4 Distruggere l'editor. 
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Specifica degli attributi deH'editor 



L'editor di proprieta deve fornire tutte quelle informazioni che 1' Object Inspector 
puo utilizzare per stabilire quali strumenti mostrare a video. Per esempio, l'Object 
Inspector deve sapere se la proprieta contiene delle sottoproprieta o puo mostrare 
una lista dei valori possibili. 

Per specificare gli attributi deH'editor, si deve ridefinire il metodo GetAttributes 
deH'editor di proprieta. 

GetAttributes e un metodo che restituisce un insieme di valori di tipo 
TProperty Attributes che possono includere uno o tutti i seguenti valori: 

Tabella 52.3 Flag attributi di un editor di proprieta 



Flag 


Metodo 
correlato 


Significato del flag, se incluso 


paValueList 


GetValues 


L'editor puo restituire un elenco di valori 






enumerati. 


paSub Properties 


GetProperties 


La proprieta ha sottoproprieta che e possibile 






visualizzare. 


paDialog 


Edit 


L'editor puo visualizzare una finestra di dialogo 




per modificare l'intera proprieta. 


paMultiSelect 


N/D 


La proprieta dovrebbe essere visualizzata quando 






l'utente seleziona piu di un componente. 


paAutoUpdate 


SetValue 


Aggiornare il componente dopo ogni modifica 






invece di aspettare la conferma del valore. 


paSortList 


N/D 


L'Object Inspector dovrebbe ordinare l'elenco dei 






valori. 


paReadOnly 


N/D 


L'utente non puo modificare il valore della 






proprieta. 


paRevertable 


N/D 


Attiva la voce di menu Revert to Inherited del menu 




contestuale dell'Object Inspector. L'elemento di 






menu dice all'editor della proprieta di scartare il 






valore corrente della proprieta e di ritornare ai 






valori impostati in precedenza o a quelli predefiniti. 


paFullWidthName 


N/D 


11 valore non e necessario che sia visualizzato. 






L'Object Inspector utilizza invece per il nome della 






proprieta la sua larghezza completa. 


paVolatileSubProperties 


GetProperties 


L'Object Inspector riaggiorna i valori di tutte le 






sottoproprieta ogni volta che il valore della 






proprieta viene modificato. 


paReference 


GetComponent 


11 valore e un riferimento a qualcos'altro. Se 




Value 


utilizzato insieme a paSub Properties 1'oggetto 






referenziato dovrebbe essere visualizzato come 






sottoproprieta di questa proprieta. 



Le proprieta Color sono piu versatili di molte altre proprieta perche consentono agli 
utenti di selezionarle in vari modi all'interno dell'Object Inspector: scrivendone il 
nome, selezionandole da una lista o usando un editor personalizzato. II metodo 
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GetAttributes di TColorProperty, pertanto, contiene diversi attributi nel valore 
restituito: 

virtual __fastcall TPropertyAttributes TColorProperty : : GetAttributes () 

{ 

return TPropertyAttributes!) « paMultiSelect « paDialog « paValueList << paRevertable; 

} 

Registrazione dell'editor di proprieta 



Una volta creato l'editor di proprieta, e necessario registrarlo all'interno di 
C++Builder. La registrazione associa un tipo di proprieta ad un determinato editor di 
proprieta. L'editor pud venire registrato con tutte le proprieta di un certo tipo o solo 
con una determinata proprieta di un tipo particolare di componente. 

Per registrare un editor di proprieta, chiamare la funzione RegisterPropertyEditor. 

RegisterPropertyEditor richiede quattro parametri: 

• Un puntatore all'informazione di tipo per il tipo di proprieta da editare. 
Specificare le informazioni di tipo in questo modo: 

__typeinfo (TMyComponent ) 

• II tipo di componente al quale questo editor si applica. Se questo parametro e null, 
l'editor viene applicato a tutte le proprieta di un determinato tipo. 

• II nome della proprieta. Questo parametro ha significato soltanto se il parametro 
precedente specifica un particolare tipo di componente. In tal caso si pud 
specificare il nome di una particolare proprieta in quel tipo di componenti al quale 
questo editor si applica. 

• II tipo di editor di proprieta da usare per modificare quella specifica proprieta. 

Di seguito e riportato uno stralcio di una funzione che registra gli editor per i 
componenti standard presenti nella Component palette: 

namespace Newcomp 

{ 

void __fastcall PACKAGE Register)) 

{ 

RegisterPropertyEditor (__typeinfo (TComponent) , OL, "", __classid (TComponentProperty) ) ; 
RegisterPropertyEditor) typeinfo (TComponentNarae) , classid (TComponent) , "Name", 

__classid (TComponentNameProperty) ) ; 
RegisterPropertyEditor (__typeinfo (TMenuItem) , __classid (TMenu) , " " , 

__classid (TMenuItemProperty) ) ; 

} 

} 

Le tre istruzioni di questa funzione mostrano tutti i possibili usi di 

RegisterPropertyEditor. 

• La prima istruzione e la piu comune. Essa registra l'editor di proprieta 
TComponentProperty per tutte le proprieta di tipo TComponent (o per i discendenti 
di TComponent che non hanno propri editor registrati). In generale, quando si 
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registra un editor di proprieta, si e creato un editor per un particolare tipo e si 
vuole utilizzarlo per tutte le proprieta di quel tipo, cosi che il secondo e il terzo 
parametro sono, rispettivamente, NULL e una stringa vuota. 

• La seconda istruzione e il tipo piu specifico di registrazione. Essa registra un editor 
per una specifica proprieta in un tipo specifico di componente. In questo caso 
l'editor e per la proprieta Name (di tipo TComponentName) di tutti i componenti. 

• La terza istruzione e piu specifica della prima, ma non cosi limitata come la 
seconda. Essa registra un editor per tutte le proprieta di tipo TMenuItem in 
componenti di tipo TMenu. 

Categorie di proprieta 



Nell'IDE, l'Object Inspector consente di nascondere e visualizzare selettivamente le 
proprieta in base a categorie di proprieta. Le proprieta dei nuovi componenti custom 
possono essere adattate a questo schema registrando le proprieta in categorie. Questa 
operazione deve essere eseguita contemporaneamente alia registrazione del 
componente chiamando RegisterPropertylnCategory o RegisterPropertiesInCategory, per 
la registrazione della proprieta. Utilizzare RegisterPropertylnCategory per registrare 
una singola proprieta. Utilizzare RegisterPropertiesInCategory per registrare piu 
proprieta con una singola chiamata alia funzione. Queste funzioni sono definite nella 
unit Designlntf . 

Si noti che non e obbligatorio registrare le proprieta o registrare tutte le proprieta di 
un componente custom nel caso se ne registrino solo alcune. Qualsiasi proprieta che 
non e associata esplicitamente con una categoria viene inclusa nella categoria 
TMiscellaneousCategory. Tali proprieta sono visualizzate, o nascoste, nell'Object 
Inspector in base alia categoria di appartenenza predefinita. 

Oltre a queste due funzioni per registrare le proprieta, esiste una funzione 
IsPropertylnCategory. Questa funzione e utile per la creazione di utilita di 
localizzazione, in cui si deve determinare se una proprieta risulta registrata in una 
data categoria di proprieta. 

Registrazione di una proprieta alia volta 



Per registrare una proprieta alia volta e associarla con una categoria di proprieta si 
utilizza la funzione RegisterPropertylnCategory. RegisterPropertylnCategory ha quattro 
varianti caricate in sovrapposizione, ognuna delle quali fornisce una serie diversa di 
criteri per identificare la proprieta nel componente custom da associare con la 
categoria di proprieta. 

La prima variante consente di identificare la proprieta in base al nome della 
proprieta. La riga seguente registra una proprieta correlata alia rappresentazione 
visuale del componente, identificando la proprieta in base al nome "AutoSize". 

RegisterPropertylnCategory ("Visual", "AutoSize") ; 

La seconda variante somiglia molto alia prima, salvo che limita la categoria solo a 
quelle proprieta con un nome determinate che appaiono in componenti di un 
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determinate) tipo. L'esempio seguente registra (nella categoria 'Help and Hints') una 
proprieta di nome "HelpContext" di un componente appartenente alia classe custom 
TMyButton. 

RegisterPropertylnCategoryC'Help and Hints", __classid (TMyButton) , "HelpContext"); 

La terza variante identifica la proprieta utilizzandone il tipo invece del nome. 
L'esempio seguente registra una proprieta in base al tipo, una classe speciale di nome 
T Arrangement . 

RegisterPropertylnCategory ( 'Visual' , typeid(TArrangement) ) ; 

La variante finale utilizza entrambi i tipi della proprieta e il suo nome per identificare 
la proprieta. L'esempio seguente registra una proprieta in base a una combinazione 
del tipo, TBitmap, e del nome, "Pattern." 

RegisterPropertylnCategory ("Visual", typeid(TBitmap) , "Pattern") ; 

Per un elenco delle categorie di proprieta disponibili e una breve descrizione del loro 
uso, consultare la sezione Specifica delle categorie di proprieta. 



Registrazione contemporanea di piu proprieta 



La registrazione contemporanea di piu proprieta e la loro associazione con una 
categoria di proprieta avviene utilizzando la funzione Register PropertiesInCategory. 
RegisterPropertiesInCategory ha tre varianti caricate in sovrapposizione, ognuna delle 
quali fornisce una serie diversa di criteri per identificare la proprieta nel componente 
custom da associare alle categorie di proprieta. 

La prima variante consente di identificare le proprieta in base al nome o al tipo di 
proprieta. L' elenco viene passato come un array di costanti. Nell'esempio seguente, 
tutte le proprieta che hanno come nome "Text" o che appartengono a una classe di 
tipo TEdit vengono registrate nella categoria 'Localizable.' 

RegisterPropertiesInCategory ( "Localizable" , ARRAYOFCONST ( " Text " , __typeinfo (TEdit))); 

La seconda variante consente di limitare le proprieta registrate solo a quelle che 
appartengono a un determinato componente. L'elenco delle proprieta da registrare 
include solamente i nomi e non i tipi. Ad esempio, il codice seguente registra diverse 
proprieta di tutti i componenti nella categoria 'Help and Hints: 

RegisterPropertylnCategory ("Help and Hints", __classid (TComponent ) , 
ARRAYOFCONST ("HelpContext", "Hint", "ParentShowHint " ) ) ; 

La terza variante consente di limitare le proprieta registrate solo a quelle che hanno 
un determinato tipo. Come nel caso della seconda variante, l'elenco delle proprieta 
da registrare puo includere solamente i nomi: 

RegisterPropertiesInCategory ( "Localizable" , __typeinfo (TStrings) , ARRAYOFCONST ( "Lines " , 
"Commands" ) ) ; 

Per un elenco delle categorie di proprieta disponibili e una breve descrizione del loro 
uso, consultare la sezione Specifica delle categorie di proprieta. 



52-14 Guida alia programmazione 



Categorie di proprieta 



Specifica delle categorie di proprieta 



Quando si registrano le proprieta in una categoria, e possibile utilizzare come nome 
della categoria qualsiasi stringa si desideri. Se si utilizza una stringa che non e stata 
utilizzata in precedenza, l'Object Inspector genera una nuova classe di categoria di 
proprieta con quel nome. E possibile anche, pero, registrare le proprieta in una delle 
categorie native. Le categorie di proprieta native sono descritte nella Tabella 52.4.: 

Tabella 52.4 Categorie di proprieta 



Categoria 

Action 

Database 

Drag, Drop, and 
Docking 

Help and Hints 

Layout 

Legacy 

Linkage 

Locale 

Localizable 



Visual 



Input 



Miscellaneous 



Scopo 

Proprieta relative ad azioni in esecuzione; le proprieta Enabled e Hint di 
TEdit appartengono a questa categoria. 

Proprieta relative a operazioni di database; le proprieta DatabaseName e 
SQL di TQuery appartengono a questa categoria. 

Proprieta relative a operazioni drag-and-drop e drag-and-dock; le 
proprieta DragCursor e DragKind di TImage appartengono a questa 
categoria. 

Proprieta relative all'utilizzo della Guida in linea o dei suggerimenti; le 
proprieta HelpContext e Hint di TMemo appartengono a questa categoria. 

Proprieta relative alia rappresentazione visuale di un controllo in fase di 
progettazione; le proprieta Top e Left di TDBEdit appartengono a questa 
categoria. 

Proprieta relative a operazioni obsolete; le proprieta Ctl3D e ParentCtl3D 
di TComboBox appartengono a questa categoria. 

Proprieta relative all'associazione o al collegamento di un componente a 
un altro; la proprieta DataSet di TDataSource e in questa categoria 

Proprieta relative alle impostazioni locali internazionali; le proprieta 
BiDiMode e ParentBiDiMode di TMainMenu appartengono a questa 
categoria. 

Proprieta che potrebbe essere necessario modificare nell versioni 
nazionali di un'applicazione. In questa categoria rientrano diverse 
proprieta di tipo string (come Caption), in quanto sono proprieta che 
determinano le dimensioni e la posizione dei controlli. 

Proprieta relative alia rappresentazione visuale di un controllo in fase di 
esecuzione; le proprieta Align e Visible di TScrollBox appartengono a 
questa categoria. 

Proprieta relative aH'inserimento di dati (non necessariamente collegate 
ad operazioni su database); le proprieta Enabled e Readonly di TEdit 
appartengono a questa categoria. 

Proprieta che non rientrano in una categoria, che non hanno bisogno di 
essere raggruppate in una categoria (o che non sono state registrate 
esplicitamente in una certa categoria); le proprieta Allow AllUp e Name 
di TSpeedButton appartengono a questa categoria. 



Utilizzo della funzione IsPropertylnCategory 



Un'applicazione puo interrogare le proprieta registrate esistenti per determinare se 
una certa proprieta e gia registrata in una determinata categoria. Questa capacita puo 
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risultare particolarmente utile in programmi di utilita per la localizzazione che 
eseguono un controllo preliminare sull'appartenenza ad una categoria di proprieta 
per compiere operazioni di localizzazione. La funzione IsPropertylnCategory dispone 
di due varianti, caricate in sovrapposizione, che consentono l'uso di criteri differenti 
nel determinare se una proprieta appartiene ad una certa categoria. 

La prima variante consente di basare il criterio di confronto su una combinazione del 
tipo di classe del proprio componente e del nome della proprieta. Nella riga di 
comando seguente, affinche IsPropertylnCategory restituisca true, la proprieta deve 
appartenere al discendente TCustomEdit, avere come nome "Text", e deve essere nella 
categoria di proprieta di nome 1 Localizable 1 . 

IsItThere = IsPropertylnCategory ("Localizable", __classid(TCustomEdit) , "Text"); 

La seconda variante consente di basare il criterio di confronto su una combinazione 
del nome di classe del proprio componente e del nome della proprieta. Nella riga di 
comando seguente, affinche IsPropertylnCategory restituisca true, la proprieta deve 
appartenere al discendente TCustomEdit, avere come nome "Text" , e deve essere nella 
categoria di proprieta di nome 1 Localizable 1 . 

IsItThere = IsPropertylnCategory ("Localizable", "TCustomEdit", "Text"); 

Aggiunta di editor di componenti 



Gli editor di componenti determinano che cosa accade quando si fa doppio clic sul 
componente nel designer e aggiungono comandi al menu contestuale che appare 
quando si fa clic con il pulsante destro. Essi sono anche in grado di copiare il 
componente nella clipboard di Windows in formati custom. 

Se non viene fornito nessun editor di componente ai propri componenti, C++Builder 
utilizza l'editor di componente predefinito. L'editor di componente predefinito e 
implementato dalla classe TDefaultEditor. TDefaultEditor non aggiunge nessuna 
nuova voce al menu contestuale del componente. Quando si fa doppio clic sul 
componente, TDefaultEditor cerca le proprieta del componente e genera (o si sposta 
su) il primo gestore di eventi che trova. 

Per aggiungere delle voci al menu contestuale, modificare il comportamento quando 
si fa doppio clic sul componente, o aggiungere nuovi formati clipboard, derivare una 
nuova classe da TComponentEditor e registrarne l'uso con il proprio componente. Nei 
propri metodi ridefiniti si puo utilizzare la proprieta Component di TComponentEditor 
per accedere al componente da modificare. 

L'aggiunta di un editor di componente custom e una procedura composta dalle 
seguenti fasi: 

• Aggiunta di voci al menu contestuale 

• Modifica del comportamento del doppio clic 

• Aggiunta di formati nella clipboard 

• Registrazione dell'editor di componente 
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Aggiunta di voci al menu contestuale 



Quando l'utente fa clic con il tasto destro del mouse sul componente, vengono 
chiamati i metodi GetVerbCount e GetVerb del componente editor per creare il menu 
contestuale. Questi metodi possono essere ridefiniti aggiungendo comandi (verbi) al 
menu contestuale. 

L'aggiunta di elementi al menu contestuale richiede le seguenti fasi: 

• Specifica delle voci di menu 

• Implementazione dei comandi 

Specifica delle voci di menu 

Ridefinire il metodo GetVerbCount per restituire il numero di comandi aggiunti al 
menu contestuale. Ridefinire il metodo GetVerb per restituire le stringhe che devono 
essere aggiunte ad ognuno di questi comandi. Quando si ridefinisce GetVerb, 
aggiungere una e commerciale (&) alia stringa per fare in modo che il carattere che 
segue la e commerciale nella stringa appaia sottolineato nel menu contestuale e 
funzioni come tasto di scelta rapida per la selezione della voce di menu 
corrispondente. Assicurarsi di aggiungere simbolo ellissi (...)alla fine di un comando 
se questo richiama una finestra di dialogo. GetVerb ha un singolo parametro che 
indica l'indice del comando. 

II codice seguente ridefinisce i metodi GetVerbCount e GetVerb per aggiungere due 
comandi al menu contestuale. 

int __fastcall TMyEditor: : GetVerbCount (void) 
{ 

return 2; 

} 

System: :AnsiString fastcall TMyEditor: :GetVerb(int Index) 

{ 

switch (Index) 
{ 

case 0: return "iDoThis break; 
case 1: return "Do&That"; break; 

} 

} 

E bene assicurarsi che il proprio metodo GetVerb restituisca un valore per ogni 
possibile indice indicato da GetVerbCount. 

Implementazione dei comandi 

Quando si seleziona un comando fornito da GetVerb nella funzione di impostazione, 
viene chiamato il metodo ExecuteVerb. Per ogni comando fornito nel metodo GetVerb, 
implementare un'azione nel metodo ExecuteVerb. Utilizzando la proprieta Component 
dell'editor, si pud accedere al componente da modificare. 

Ad esempio, il seguente metodo ExecuteVerb implementa i comandi per il metodo 
GetVerb dell'esempio precedente. 

void fastcall TMyEditor: : ExecuteVerb (int Index) 

{ 
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switch (Index) 
{ 

case 0: 

TMyDialog *MySpecialDialog = new TMyDialog () ; 
MySpecialDialog->Execute ( ) ; 

( (TMyComponent *) Component ) ->ThisProperty = MySpecialDialog->ReturnValue; 
delete MySpecialDialog; 
break ; 
case 1: 

ThatO; // call the "That" method 
break ; 

} 

} 

Modifica del comportamento del doppio die 



Quando si fa doppio clic sul componente, viene chiamato il metodo Edit dell'editor di 
componente. II metodo Edit, come impostazione predefinita, esegue il primo 
comando aggiunto al menu contestuale. Quindi, nell'esempio precedente, facendo 
doppio clic sul componente viene eseguito il comando Dofhis. 

Anche se l'esecuzione del primo comando e generalmente una buona idea, si pud 
anche decidere di cambiare questo comportamento predefinito. Ad esempio, si puo 
voler fornire un comportamento alternative se 

• non si aggiunge nessun comando al menu contestuale. 

• si vuole che compaia una finestra di dialogo che combina diversi comandi quando 
si fa doppio clic sul componente. 

Ridefinire il metodo Edit per specificare un nuovo comportamento quando si fa 
doppio clic sul componente. Per esempio, il seguente metodo Edit apre una finestra 
di dialogo font quando l'utente fa doppio clic sul componente: 

void __fastcall TMyEditor: :Edit (void) 

{ 

TFontDialog *pFontDlg = new TFontDialog (NULL) ; 
pFontDlg->Execute ( ) ; 

((TMyComponent *) Component ) ->Font = pFontDlg->Font ; 
delete pFontDlg; 

} 

Se si vuole visualizzare il Code editor per un gestore di eventi quando si fa doppio 
clic sul componente, utilizzare TDefaultEditor come classe basse per il proprio editor 
del componente al posto di TComponentEditor. Quindi, invece di ridefinire il metodo 
Edit, ridefinire in sua vece il metodo protetto TDefaultEditor.-.EditProperty. 
EditProperty ef fettua un scansione dei gestori di eventi del componente, e attiva il 
primo che trova. Questo processo puo essere modificato facendo si che venga cercato 
uno specifico gestore di eventi. Per esempio: 

void __fastcall TMyEditor: : EditProperty (TPropertyEditor* PropertyEditor, 

bool &Continue, bool &FreeEditor) 

{ 

if (PropertyEditor->ClassNameIs ("TMethodProperty") && 
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CompareText (PropertyEditor->GetName, "OnSpecialEvent") == 0) 

{ 

TDefaultEditor: :EditProperty (PropertyEditor, Continue, FreeEditor) ; 

} 

} 

Aggiunta di formati nella clipboard 



Per impostazione predefinita, quando un utente sceglie Copy mentre c'e un 
componente selezionato nell'IDE, il componente viene copiato utilizzando il formato 
interno di C++Builder. Tale componente puo, a questo punto, essere incollato in 
un'altra scheda o in un modulo dati. Un componente puo copiare ulteriori formati 
nella clipboard di Windows ridefinendo il metodo Copy. 

Per esempio, il seguente metodo Copy permette a un componente TImage di copiare la 
sua immagini nella clipboard. Questa immagine viene ignorata dall'IDE di 
C++Builder, ma puo essere incollata in un'altra applicazione. 

void __fastcall TMyComponentEditor: :Copy (void) 

{ 

WORD AFormat; 
int AData; 
HPALETTE APalette; 

((TImage *) Component ) ->Picture->SaveToClipboardFormat (AFormat, AData, APalette); 
TClipboard *pClip = Clipboard!); // don't clear the clipboard! 
pClip->SetAsHandle (AFormat, AData) ; 

} 

Registrazione dell'editor di componente 



Una volta definito l'editor del componente, puo essere registrato in modo che sia in 
grado di operare con una particolare classe di componenti. Viene creato un editor di 
componente registrato per ogni componente di quella classe quando lo si seleziona 
nel Form designer. 

Per creare l'associazione tra un editor di componente e una classe di componente, 
chiamare Register ComponentEditor. RegisterComponentEditor Prende il nome della 
classe del componente che utilizza l'editor, e il nome della classe dell'editor del 
componente che e stato definito. Per esempio, la seguente istruzione registra una 
classe dell'editor di componente chiamata TMyEditor perche funzioni con tutti i 
componenti di tipo TMyComponent: 

RegisterComponentEditor (__classid ( TMyComponent) , __classid (TMyEditor) ) ; 

Collocare la chiamata a RegisterComponentEditor nel namespace in cui si registra il 
componente. Per esempio, se un nuovo componente di nome TMyComponent e il suo 
editor di componente TMyEditor sono entrambi implementati in NewComp.cpp, il 
codice seguente (in NewComp.cpp) registra il componente e la sua associazione con 
il componente editor. 

namespace Newcomp 

{ 
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void __fastcall PACKAGE Register!) 

{ 

TMetaClass classes [1] = {__classid (TMyComponent) } ; 
RegisterComponents ( "Miscellaneous", classes, 0); 
RegisterComponentEditor (classes [0] , __classid (TMyEditor) ) ; 

} 

} 

Compilazione dei componenti in package 



Una volta che i componenti sono stati registrati, occorre compilarli come package 
prima di poterli installare nell'IDE. Un package puo contenere uno o piu componenti 
oltre a vari editor di proprieta personalizzati. Per ulteriori informazioni sui package, 
consultare ilCapitolo 15, "Uso di package e di componenti". 

Per creare e compilare un package, seguire le istruzioni contenute nel paragrafo 
"Creazione ed editing dei package" a pagina 15-7. Inserire le unit del codice sorgente 
per i propri componenti personalizzati nella lista Contains del package. Se i propri 
componenti dipendono da altri package, includere tali package nella lista Requires. 

Per installare i propri componenti nell'IDE, seguire le istruzioni riportate nel 
paragrafo "Installazione di package di componenti" a pagina 15-6. 

Risoluzione dei problemi con componenti custom 



Un problema frequente, che si verifica durante la registrazione e l'installazione di 
componenti custom, e che il componente non viene visualizzato nella lista dei 
componenti, pur avendo installato con successo il package. 

Le cause piu comuni che impediscono la visualizzazione dei componenti nell'elenco 
o nella tavolozza sono: 

• Mancanza del modificatore PACKAGE nella funzione Register 

• Mancanza del modificatore PACKAGE nella classe 

• Mancanza della direttiva #pragma package (smart_init ) nel file sorgente in C++ 

• La funzione Register non e presente in un namespace avente lo stesso nome del 
nome del modulo del codice sorgente. 

• La funzione Register non viene esportata con successo. Utilizzare il programma di 
utilita TDUMP sul file .BPL per esaminare le funzioni esportate: 

tdump -ebpl mypack.bpl mypack . dmp 

Nella sezione del dump relativa all'esportazione, si dovrebbe vedere che la 
funzione Register (all'intemo del namespace) viene esportata. 
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Modifies di un componente esistente 

II modo piu semplice per creare un componente consiste nel derivarlo da un altro 
quanto piu possibile simile a quello desiderato, apportandovi poi le modifiche 
necessarie. L'esempio riportato in questo capitolo modifica il componente standard 
memo per creare un memo con lo sfondo di colore giallo. Negli altri capitoli di questa 
sezione viene descritta la creazione di componenti piu complessi. II processo base e 
sempre lo stesso, ma i componenti piu complessi richiedono un maggior numero di 
operazioni per personalizzare la nuova classe. 

La modifica di un componente esistente richiede solamente due fasi: 

• Creazione e registrazione del componente 

• Modifica della classe del componente 

Creazione e registrazione del componente 



La creazione di qualunque componente comincia nello stesso modo: si deriva la 
classe di un componente, si salvano i file .CPP e .H del componente, si registra il 
componente, lo si compila e lo si installa nella Component palette. Questo processo 
viene descritto nella sezione "Creazione di un nuovo componente" a pagina 45-8. 

Per creare un componente con le specifiche desiderate, seguire questa procedura: 

1 Assegnare alia unit del componente il nome YelMemo e salvarla, in modo che il file 
header sia YELMEMO. H e il file .CPP sia YELMEMO.CPP. 

2 Derivare un nuova classe di componente di nome TYelloivMemo, facendolo 
discendere dalla classe TMemo. 

3 Registrare TYellowMemo nella pagina Samples (o in un'altra pagina della CLX) 
della Component palette. 
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II file header risultante dovrebbe apparire simile al seguente: 

♦ifndef YelMemoH 
♦define YelmemoH 
// 

♦include <sysutils .hpp> 
♦include <controls .hpp> 
♦include <classes .hpp> 
♦include <forms.hpp> 
♦include <StdCtrls .hpp> 
// 

class PACKAGE TYellowMerao : public TMemo 
{ 

private: 

protected: 

public: 

__published: 

}; 

// 

♦endif 

II file .CPP associato sara piu o meno come questo: 

♦include <vcl.h> 
♦pragma hdrstop 
♦include "Yelmerao.h" 

// 

♦pragma package (smart_init ) ; 

// 

// ValidCtrCheck is used to assure that the components created do not have 
// any pure virtual functions. 

// 

static inline void ValidCtrCheck (TYellowMerao *) 

{ 

new TYellowMerao (NULL) ; 

} 

// 

fastcall TYellowMemo: :TYellowMemo (TComponent* Owner) 

: TMemo (Owner) 

{ 
} 

// 

namespace Yelmemo 
{ 

void __fastcall PACKAGE Register!) 
{ 

TComponentClass classes [1] = {__classid(TYellowMemo) } ; 

RegisterComponents ( " Samples", classes, 0); //"Common Controls" in CLX applications 

} 

} 

Nelle applicazioni CLX i nomi e le ubicazioni di alcuni file header sono differenti. Ad 
esempio, <vcl\controls .hpp> e <clx\qcontrols .hpp> in CLX. 
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In questo esempio si presuppone che non si utilizzi il Component wizard per creare 
questo componente, ma che si proceda manualmente. Se si usa il Component wizard, 
verra aggiunto automaticamente un costruttore a TYellowMemo. 



Modifica della classe del componente 



Una volta creata una nuova classe di componente, e possibile modificarla 
praticamente in qualsiasi modo. In questo caso, si modifichera solamente il valore 
iniziale di una proprieta del componente memo. Cio comporta due piccole modifiche 
alia classe del componente: 

• Ridefinizione del costruttore. 

• Specifica del nuovo valore predefinito di una proprieta. 

E il costruttore che, di fatto, imposta il valore della proprieta. II valore predefinito 
impostato dice a C++Builder quali valori memorizzare nel file scheda (.dfm per la 
VCL e .xfm per la CLX). C++Builder memorizza solamente i valori che differiscono 
da quelli predefiniti, quindi e importante compiere entrambe queste operazioni. 



Ridefinizione del costruttore 



Quando un componente viene collocato su una scheda in fase di progetto, o quando 
un'applicazione costruisce un componente durante l'esecuzione, il costruttore del 
componente imposta i valori delle relative proprieta. Quando un componente viene 
caricato da un file scheda, l'applicazione imposta tutte le proprieta modificate in fase 
di progetto. 

Quando si ridefinisce un costruttore, il nuovo costruttore deve chiamare il costruttore 
ereditato prima di fare qualsiasi altra cosa. Per ulteriori informazioni consultare il 
paragrafo "Ridefinizione dei metodi" a pagina 46-10. 

In questo esempio, il nuovo componente necessita della ridefinizione del costruttore 
ereditato da TMemo per impostare la proprieta Color a clYellow. A questo scopo, 
aggiunge la dichiarazione di ridefinizione del costruttore alia dichiarazione della 
classe, quindi scrive il nuovo costruttore nel file .CPP: 

class PACKAGE TYellowMemo : public TMemo 
{ 

public: 

virtual fastcall TYellowMemo (TComponent* Owner); // the constructor declaration 

published: 

__property Color; 

}; 

fastcall TYellowMemo: :TYellowMemo (TComponent* Owner) 

: TMemo (Owner) // the constructor implementation first... 

// ...calls the constructor for TMemo 

{ 

Color = clYellow; // colors the component yellow 

} 
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Se per creare il componente si e utilizzato il Component wizard, e sufficiente soltanto 
aggiungere Color = clYellow; al costruttore esistente. 

A questo punto e possibile installare il nuovo componente nella Component palette e 
aggiungerlo alia scheda. La proprieta Color predefinita ora e clYellow. 

Specifica del nuovo valore predefinito di una proprieta 



Quando C++Builder memorizza la descrizione di una scheda in un file scheda, 
memorizza solo i valori delle proprieta che differiscono da quelli predefiniti. La 
memorizzazione dei soli valori che differiscono da quelli predefiniti aiuta a 
mantenere piccoli i file di scheda e rende piu rapido il caricamento della scheda. Se si 
crea una proprieta o si modifica il valore predefinito, pud essere utile aggiornare la 
dichiarazione della proprieta per includere il nuovo valore predefinito. I file di 
scheda, il caricamento e i valori predefiniti sono spiegati piu dettagliatamente nel 
Capitolo 52, "Come rendere disponibili i componenti in fase di progetto". 

Per modificare il valore predefinito di una proprieta: 

1 Ridichiarare il nome della proprieta. 

2 Porre un segno uguale (=) dopo il nome della proprieta. 

3 Scrivere la parola chiave default, un altro segno uguale e il valore predefinito, 
racchiudendo il tutto fra parentesi graffe. 

Si noti che non e necessario dichiarare di nuovo l'intera proprieta, ma solo il nome e il 
valore predefinito. 

Per il componente memo yellow, si deve dichiarare di nuovo la proprieta Color in una 

sezione published della dichiarazione della classe, con un valore predefinito pari a 

clYellow: 

class PACKAGE TYellowMemo : public TMemo 
{ 

public : 

virtual fastcall TYellowMemo (TComponent* Owner); 

..published: 

..property Color = {default=clYellow} ; 

}; 

Ecco di nuovo TYellowMemo, ma questa volta ha un'altra proprieta published, 
Wordwrap, con un valore predefinito impostato a false: 

class PACKAGE TYellowMemo : public TMemo 
{ 

public: 

virtual fastcall TYellowMemo (TComponent* Owner); 

published: 

..property Color = {default=clYellow} ; 
property Wordwrap = {default=false} ; 

}; 
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La specifica del valore predefinito della proprieta non influenza minimamente il 
funzionamento del componente. Occorre ancora impostare esplicitamente il valore 
predefinito del costruttore del componente. La differenza sta nel funzionamento 
interno dell'applicazione. Per TYellowMemo, C++Builder non scrivera piu Wordwrap 
nel file scheda se e false, perche gli e stato comunicato che il costruttore impostera 
automaticamente quel valore. Ecco il codice del costruttore: 

fastcall TYellowMemo: :TYellowMemo (TComponent* AOwner) : TMemo (AOwner) 

{ 

Color = clYellow; 
Wordwrap = false; 

} 
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Creazione di un controllo grafico 

Un controllo grafico e un tipo di componente semplice. Poiche un controllo 
esclusivamente grafico non riceve mai il fuoco, non possiede ne richiede un handle di 
finestra. Gli utenti possono comunque gestire il controllo col mouse, ma non c'e una 
interfaccia di tastiera. 

II componente grafico presentato in questo capitolo e TShape, il componente shape 
che appare nella pagina Additional della Component palette. Anche se il 
componente che viene creato e identico al componente shape standard, e necessario 
chiamarlo in modo diverso per evitare duplicati di identificatori. In questo capitolo al 
componente viene assegnato il nome TSampleShape e vengono illustrati tutti i passi 
necessari alia sua creazione: 

• Creazione e registrazione del componente 

• Pubblicazione delle proprieta ereditate 

• Aggiunta di funzionalita grafiche 



Creazione e registrazione del componente 



La creazione di qualunque componente inizia nello stesso modo: si deriva una classe 
di componente, si salvano i file .CPP e .H del componente, si registra il componente, 
lo si compila e lo si installa nella Component palette. Questo processo viene descritto 
nella sezione "Creazione di un nuovo componente" a pagina 45-8. 

In questo esempio si presuppone che non si utilizzi Component wizard, ma che si 
crei il componente manualmente. 

Per questo esempio, seguire la procedura generale di creazione di un componente, 
con queste speciriche: 

1 Derivare un nuovo tipo di componente chiamato TSampleShape, discendente da 
TGraphicControl. 



Creazione di un controllo grafico 54-1 



Creazione e registrazione del componente 

2 Chiamare il file header del componente SHAPES.H e il file .CPP associato 
SHAPES.CPP. 

3 Registrare TSampleShape nella pagina Samples (o in un'altra pagina della CLX) 
della Component palette. 

II file header risultante sara simile al seguente: 

// 

♦ifndef ShapesH 
♦define ShapesH 

// 

♦include <sysutils .hpp> 
♦include <controls .hpp> 
♦include <classes .hpp> 
♦include <forms.hpp> 

// 

class PACKAGE TSampleShape : public TGraphicControl 

{ 

private: 

protected: 

public: 

__published: 

}; 

// 

♦endif 

II file .CPP sara piu o meno come questo: 

// 

♦include <vcl.h> 
♦pragma hdrstop 
♦ include " Shapes. h 11 

// 

♦pragma package (smart_init ) ; 

// 

// ValidCtrCheck is used to assure that the components created do not have 
// any pure virtual functions. 

// 

static inline void ValidCtrCheck (TSampleShape *) 

{ 

new TSampleShape (NULL) ; 

} 

// 

__fastcall TSampleShape: :TGraphicControl (TComponent* Owner) 
: TGraphicControl (Owner) 

{ 
} 

// 

namespace Shapes 

{ 

void __fastcall PACKAGE Register!) 
{ 

TComponentClass classes [1] = {__classid(TSampleShape) } ; 
RegisterComponents ( "Samples", classes, 0); 
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} 

} 

Nelle applicazioni CLX i nomi e le ubicazioni di alcuni file header sono differenti. Ad 
esempio, <vcl\controls.hpp> e <clx\qcontrols.hpp> in CLX. 

Pubblicazione delle proprieta ereditate 



Una volta derivato un tipo di componente, si puo decidere quali proprieta ed eventi, 
dichiarati nelle sezioni protette della classe antenato, si vogliono rendere disponibili 
nel nuovo componente. TGraphicControl pubblica gia tutte le proprieta che 
consentono al componente di funzionare come un controllo, per cui, Tunica cosa che 
occorre rendere pubblica e la capacita di rispondere agli eventi del mouse e di gestire 
le operazioni drag-and-drop. 

II modo per rendere pubbliche le proprieta e gli eventi ereditati e spiegato nel 
paragrafo "Pubblicazione di proprieta ereditate" a pagina 47-3 e "Visibilita degli 
eventi" a pagina 48-5. Entrambi i processi includono la ridichiarazione del nome 
delle proprieta nella sezione published della dichiarazione della classe. 

Per il controllo shape e possibile rendere pubblici i tre eventi del mouse, le due 
proprieta e i tre eventi relativi alle operazioni di drag-and-drop: 

class PACKAGE TSampleShape : public TGraphicControl 
{ 

private: 
published: 

property DragCursor ; 

property DragMode ; 

property OnDragDrop ; 

property OnDragOver ; 

property OnEndDrag ; 

property OnMouseDown ; 

property OnMouseMove ; 

__property OnMouseUp ; 

}; 

II controllo shape dell'esempio rende disponibili agli utenti le interazioni del mouse e 
il drag-and-drop. 

Aggiunta di funzionalita grafiche 



Una volta dichiarato il componente grafico e resa pubblica ogni proprieta ereditata 
che si vuole rendere disponibile, e possibile aggiungere alcune funzionalita grafiche 
che distinguano il componente. Durante la creazione di un controllo grafico, vengono 
compiute due operazioni: 

1 Determinazione di cosa disegnare. 

2 Disegno dell'immagine del componente. 
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Inoltre, al nostro controllo shape di esempio verranno aggiunte alcune proprieta che 
permetteranno agli sviluppatori di applicazioni di personalizzare il controllo 
modificandone l'aspetto durante lo sviluppo. 

Determinazione di cosa disegnare 



Un controllo grafico pud modificare il proprio aspetto per riflettere una condizione 
dinamica, incluso l'input dell'utente. Un controllo grafico che non varia mai non 
sarebbe probabilmente neanche un componente. Se si vuole un'immagine statica, 
invece di usare un controllo, la si puo importare. 

In generale, l'aspetto di un controllo grafico dipende da alcune combinazioni delle 
proprieta. II controllo Gauge, per esempio, ha proprieta che ne determinano forma e 
orientamento oltre a determinare se mostrare l'evolversi di un processo 
numericamente e/o graficamente. Similmente, il controllo shape ha proprieta che 
determinano quale tipo di figura deve tracciare. 

Per attribuire al controllo una proprieta che determini la figura da disegnare, 
aggiungere un proprieta di nome Shape.Cib richiede 

1 Dichiarzione del tipo della proprieta. 

2 Dichiarazione della proprieta. 

3 Scrittura del metodo di implementazione. 

La creazione di proprieta e illustrata piu dettagliatamente nel Capitolo 47, 
"Creazione di proprieta". 

Dichiarzione del tipo della proprieta 

Quando si dichiara la proprieta di un tipo definito dall'utente, prima della classe che 
include la proprieta si deve dichiarare il tipo. La categoria piu comune dei tipi di 
proprieta definiti dall'utente e quello enumerato. 

Aggiungere la seguente definizione di tipo prima della dichiarazione della classe del 
controllo shape. 

enum TSampleShapeType { sstRectangle, sstSquare, sstRoundRect, sstRoundSquare, sstEllipse, 
sstCircle }; 

class PACKAGE TSampleShape : public TGraphicControl // this is already there 

E possibile ora utilizzare questo tipo per dichiarare una nuova proprieta all'interno 
della classe. 

Dichiarazione della proprieta 

Quando si dichiara una proprieta, solitamente e necessario dichiarare un membro 
dati privato per registrare i dati delle proprieta, quindi specificare i metodi di lettura 
e/o scrittura del valore della proprieta. Spesso non e necessario utilizzare un metodo 
per leggere il valore, ma e sufficiente puntare ai dati registrati. 

Per il controllo shape bisogna dichiarare un membro dati che contenga la figura 
attiva, quindi dichiarare una proprieta che legga e scriva tale membro dati 
richiamando un metodo. 
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Aggiungere la seguente dichiarazione a TSampleShape: 

class PACKAGE TSampleShape : public TGraphicControl 
{ 

private: 

TSampleShapeType FShape; 

void __fastcall Set Shape (TSampleShapeType Value); 
__published: 

__property TSampleShapeType Shape = {read=FShape, write=SetShape, nodefault}; 

}; 

Ora tutto cio che rimane da fare e aggiungere 1'implementazione di SetShape. 

Scrittura del metodo di implementazione 

Quando la parte read o write della definizione della proprieta usa un metodo invece 
di accedere direttamente ai dati memorizzati della proprieta, occorre implementare il 
metodo. 

Aggiungere 1'implementazione del metodo SetShape al file SHAPES.CPP: 

void __fastcall TSampleShape: : SetShape (TSampleShapeType Value) 
{ 

if (FShape != Value) // ignore if this isn't a change 

{ 

FShape = Value; // store the new value 

Invalidated; // force a repaint with the new shape 

} 

} 

Ridefinizione del costruttore e del distruttore 



Per modificare i valori predefiniti della proprieta e inizializzare le classi possedute 
dal componente, si deve ridefinire il costruttore e il distruttore ereditati. In entrambi i 
casi, bisogna ricordarsi di chiamare il metodo ereditato nel nuovo costruttore o 
distruttore. 

Cambiamento dei valori predefiniti delle proprieta 

Poiche la dimensione predefinita di un controllo grafico e piuttosto piccola, e 
possibile cambiarne la larghezza e l'altezza all'intemo del metodo costruttore. II 
cambiamento dei valori predefiniti delle proprieta e spiegato in maniera piu 
dettagliata nel Capitolo 53, "Modifica di un componente esistente". 

In questo esempio il controllo shape imposta le proprie dimensioni ad un quadrato di 
65 pixel per lato. 

Aggiungere il costruttore ridefinito alia dichiarazione della classe del componente: 

class PACKAGE TSampleShape : public TGraphicControl 
{ 

public: 

virtual __fastcall TSampleShape (TComponent *0wner); 

}; 
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Se si e iniziata la creazione del componente mediante il wizard Component, questa 
operazione e gia stata eseguita automaticamente. 

Ridichiarare le proprieta Height e Width con i loro nuovi valori predefiniti: 

class PACKAGE TSampleShape : public TGraphicControl 
{ 

__published: 

property Height; 

__property Width; 

} 

Scrivere il nuovo costruttore nel file .CPP: 

fastcall TSampleShape: : TSampleShape (TComponent* Owner) ; TGraphicControl (Owner) 

{ 

Width = 65; 
Height = 65; 

} 

Se si utilizza il wizard Component, tutto cio che occorre fare e aggiungere i nuovi 
valori predefiniti al costruttore gia esistente. 

Pubblicazione di penna e pennello 



Per impostazione predefinita, un canvas ha una penna nera e sottile e un pennello 
bianco e pieno. Per consentire agli sviluppatori di modificare la penna e il pennello, si 
devono preparare le relative classi da gestire in fase di progetto e successivamente 
copiarle nel canvas durante la creazione delle immagini. Le classi, quali ad esempio, 
una penna o un pennello aggiuntivi, sono chiamate classi possedute perche il 
componente le possiede ed e responsabile della loro creazione e distruzione. 

Per gestire le classi possedute occorre seguire le seguenti operazioni: 

1 Dichiarazione dei membri dati della classe. 

2 Dichiarazione delle proprieta di accesso. 

3 Inizializzazione delle classi possedute. 

4 Impostazione delle proprieta delle classi possedute. 

Dichiarazione dei membri dati della classe 

Ciascuna classe posseduta da un componente deve avere un proprio membro dati 
dichiarato nel componente. II membro dati assicura che il componente abbia sempre 
un puntatore all'oggetto posseduto cosi da poter distruggere la classe prima di 
distruggere se stesso. In generale, un componente inizializza gli oggetti posseduti nel 
proprio costruttore e li distrugge nel proprio distruttore. 

I membri dati degli oggetti posseduti sono quasi sempre dichiarati come privati. Se le 
applicazioni (o gli altri componenti) devono accedere agli oggetti posseduti, si 
possono dichiarare appositamente proprieta published o public. 

Aggiungere i membri dati per una penna ed un pennello al controllo shape: 
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class PACKAGE TSampleShape : public TGraphicControl 

{ 

private: // data members are always private 

TPen *FPen; //a data member for the pen object 

TBrush *FBrush; // a data member for the brush object 

}; 

Dichiarazione delle proprieta di accesso 

E possibile garantire I'accesso agli oggetti posseduti di un componente dichiarando 
le proprieta del tipo degli oggetti. Questo da modo agli sviluppatori di accedere agli 
oggetti in fase di progetto o durante l'esecuzione. Solitamente, la parte read della 
proprieta referenzia solo il membro dati, ma la parte write chiama un metodo che 
consente al componente di reagire alle modifiche nell'oggetto posseduto. 

Aggiungere al controllo shape le proprieta che forniscono I'accesso ai membri dati 
penna e pennello. Si dichiareranno anche i metodi per reagire alle modifiche 
apportate alia penna o al pennello. 

class PACKAGE TSampleShape : public TGraphicControl 

{ 

private: 

TPen *FPen; 
TBrush *FBrush; 

void __fastcall SetBrush (TBrush *Value); 
void __fastcall SetPen(TPen *Value); 

__published: 

property TBrush* Brush = {read=FBrush, write=SetBrush, nodefault}; 

property TPen* Pen = {read=FPen, write=SetPen, nodefault}; 

}; 

Quindi, scrivere i metodi SetBrush e SetPen nel file .CPP: 

void __fastcall TSampleShape: : SetBrush ( TBrush* Value) 

{ 

FBrush->Assign (Value) ; 

} 

void __fastcall TSampleShape: : SetPen ( TPen* Value) 
{ 

FPen->Assign (Value) ; 

} 

L'assegnazione diretta del contenuto di Value a FBrush nel seguente modo 

FBrush = Value; 

avrebbe sovrascritto il puntatore interno per FBrush e azzerato la memoria, creando 
un buon numero di problemi di proprieta. 

Inizializzazione delle classi possedute 

Se si aggiungono delle classi al proprio componente, il costruttore del componente 
deve inizializzarle in modo che l'utente finale possa interagire con gli oggetti in fase 
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di esecuzione. In modo analogo, il distruttore del componente deve distruggere gli 
oggetti posseduti prima di distruggere se stesso. 

Poiche al controllo shape sono stati aggiunti una penna e un pennello, e necessario 
inizializzarli nel costruttore del controllo shape e distruggerli nel distruttore del 
controllo: 

1 Costruire la penna e il pennello nel costruttore del controllo shape: 

__fastcall TSampleShape: :TSampleShape (TComponent* Owner) : TGraphicControl (Owner) 

{ 

Width = 65; 
Height = 65; 

FBrush = new TBrushO; // construct the pen 

FPen = new TPen(); // construct the brush 

} 

2 Aggiungere il distruttore ridefinito alia dichiarazione della classe del componente: 

class PACKAGE TSampleShape : public TGraphicControl 

{ 

public: // destructors are always public 

virtual __fastcall TSampleShape (TComponent* Owner); 
__fastcall -TSampleShape!) ; // the destructor 

}; 

3 Scrivere il nuovo distruttore nel file .CPP: 

__fastcall TSampleShape: : -TSampleShape ( ) 

{ 

delete FPen; // delete the pen object 

delete FBrush; // delete the brush object 

} 

Impostazione delle proprieta delle classi possedute 

Come ultimo passo della gestione delle classi penna e pennello, bisogna accertarsi 
che i cambiamenti nella penna e nel pennello forzino il controllo shape a ridisegnarsi. 
La penna e il pennello hanno entrambi eventi OnChange, quindi si puo creare un 
metodo nel controllo shape e far puntare ad esso entrambi gli eventi OnChange. 

Aggiungere il metodo seguente al controllo shape e aggiornare il costruttore del 
componente per assegnare gli eventi di penna e pennello al nuovo metodo: 

class PACKAGE TSampleShape : public TGraphicControl 

{ 

public: 

void __fastcall StyleChangedfTObject* Owner); 

}; 

Assegnare il metodo StyleChanged agli eventi OnChange delle classi penna e pennello 
nel costruttore TSampleShape nel file SHAPES.CPP: 

__fastcall TSampleShape: :TSampleShape (TComponent* Owner) : TGraphicControl (Owner) 

{ 
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Width = 65; 

Height = 65; 

FBrush = new TBrushO ; 

FBrush->OnChange = StyleChanged; 

FPen = new TPen ( ) ; 

FPen->OnChange = StyleChanged; 

} 

Includere l'implementazione del metodo StyleChanged: 

void __fastcall TSampleShape: : StyleChanged) TObject* Sender) 



Dopo queste modifiche il componente viene ridisegnato in modo da rispecchiare i 
cambiamenti della penna e del pennello. 



L'elemento piu importante di un controllo grafico e il metodo con cui disegna la 
propria immagine sullo schermo. II tipo astratto TGraphicControl definisce un metodo 
di nome Paint che e possibile ridefinire per disegnare l'immagine prescelta per il 
controllo. 

II metodo Paint per il controllo shape necessita di: 

• Utilizzare la penna e il pennello selezionati dall'utente. 

• Utilizzare la forma selezionata. 

• Adeguare le coordinate in modo che quadrati e cerchi usino la stessa larghezza e la 
stessa altezza. 

La ridefinizione del metodo Paint implica due operazioni: 

1 Aggiungere Paint alia dichiarazione del componente. 

2 Scrivere il metodo Paint nel file .CPP. 

Per il controllo shape aggiungere la seguente dichiarazione alia dichiarazione della 
classe: 

class PACKAGE TSampleShape : public TGraphicControl 



Invalidated ; 



// repaints the component 



Disegno dell'immagine del componente 



protected: 

virtual void __fastcall Paint (); 



}; 



Quindi, scrivere il metodo nel file. CPP: 



void __fastcall TSampleShape: : Paint () 



int X,Y,W,H,S; 
Canvas->Pen = FPen; 
Canvas->Brush = FBrush; 
W=Width; 



// copy the component's pen 
// copy the component's brush 
// use the component width 
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H=Height; // use the component height 

X=Y=0; // save smallest for circles/squares 

if( W<H ) 

S=W; 
else 

S=H; 
switch(FShape) 
{ 

case sstRectangle: // draw rectangles and squares 

case sstSquare: 

Canvas->Rectangle(X,Y,X+W,Y+H) ; 

break; 

case sstRoundRect : // draw rounded rectangles and squares 

case sstRoundSquare: 

Canvas - >RoundRec t ( X , Y , X+W , Y+H , S / 4 , S / 4 ) ; 

break; 

case sstCircle: // draw circles and ellipses 

case sstEllipse: 

Canvas->Ellipse(X,Y,X+W,Y+H) ; 

break; 
default 

break 



Paint viene chiamato ogni volta che il controllo ha bisogno di aggiornare la sua 
immagine. I controlli vengono disegnati quando essi appaiono per la prima volta o 
quando scompare una finestra di fronte ad loro. E anche possibile forzare la 
rigenerazione deirimmagine chiamando Invalidate, come fa il metodo StyleChanged. 



Perfezionamento del disegno della figura 



II controllo shape standard fa una cosa in piu rispetto al controllo shape di esempio: 
gestisce non solo i quadra ti e i cerchi, ma anche i rettangoli e le ellissi. Per fare cio, 
occorre scrivere del codice che in grado di individuare il lato piu corto e di centrare 
l'immagine. 

Qui di seguito viene riportato il metodo Paint perfezionato che corregge i quadrati e 
le ellissi: 

void __fastcall TSampleShape: : Paint (void) 
{ 

int X,Y,W,H,S; 
Canvas->Pen = FPen; 
Canvas->Brush = FBrush; 
W=Width; 
H=Height; 
X=Y=0; 
if( W<H ) 

S=W; 
else 

S=H; 
switch(FShape) 



// copy the component's pen 

// copy the component's brush 

// use the component width 

// use the component height 

// save smallest for circles/squares 



// adjust height, width and position 
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case sstRectangle: 
case sstRoundRect : 
case sstEllipse: 

Y=X=0; 

break; 
case sstSquare: 
case sstRoundSquare: 
case sstCircle: 



X= (W-S) 
Y= (H-S) 
break; 

default: 

break; 



// origin is top-left for these shapes 



// center these horizontally 
// and vertically 



switch(FShape) 
{ 

case sstSquare: 

W=H=S; 
case sstRectangle: 

Canvas->Rectangle(X,Y,X+W,Y+H) ; 

break; 
case sstRoundSquare: 

W=H=S; 
case sstRoundRect: 

Canvas - >RoundRect ( X , Y , X+W , Y+H , S / 4 , S/ 4 ) 

break; 
case sstCircle: 

W=H=S; 
case sstEllipse: 

Canvas->Ellipse(X,Y,X+W,Y+H) ; 

break; 
default 

break 



// draw rectangles and squares 

// use shortest dimension for width and height 



// draw rounded rectangles and squares 



// draw circles and ellipses 
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Personalizzazione di una griglia 

C++Builder e dotato di componenti astratti utilizzabili come basi per i componenti 
personalizzati. I piu importanti sono le griglie e le liste. In questo capitolo e possibile 
vedere come si crea un piccolo calendario mensile partendo dalla griglia base 
TCustomGrid. 

La creazione del calendario richiede le seguenti operazioni: 

• Creazione e registrazione del componente 

• Come rendere pubbliche le proprieta ereditate 

• Cambiamento dei valori iniziali 

• Ridimensionamento delle celle 

• Riempimento delle celle 

• Scorrimento di mesi e anni 

• Scorrimento dei giorni 

Nelle applicazioni VCL, il componente che viene creato e simile al componente 
TCalendar della pagina Sample della Component palette. Nelle applicazioni CLX, 
salvare il componente in una pagina differente oppure creare una nuova pagina della 
tavolozza. Vedere "Specifica della pagina della tavolozza" a pagina 52-3 oppure 
"Component palette, adding pages" nella guida in linea. 

Creazione e registrazione del componente 



La creazione di qualsiasi componente inizia sempre nello stesso modo: si deriva la 
classe di un componente, si salvano il file .CPP e .H del componente, lo si registra, lo 
si compila e lo si installa nella Component palette. Questo processo viene descritto 
nella sezione "Creazione di un nuovo componente" a pagina 45-8. 

Per questo esempio, e necessario seguire la procedura generale per la creazione di un 
componente, con le seguenti specifiche: 

1 Derivare un nuovo componente di nome TSampleCalendar, discendente da 
TCustomGrid. 
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2 Assegnare come nome al file header del componente CLSAMP.H e al file .CPP 
associato CALSAMP.CPP. 

3 Registrare TSampleCalendar nella pagina Samples (o in un'altra pagina della CLX) 
della Component palette. Nel caso di applicazioni CLX, utilizzare una pagina 
differente della Component palette. 

II file header apparira piu o meno in questo modo: 

♦ifndef CalSampH 
♦define CalSampH 

// 

♦include <vcl\sysutils.hpp> 
♦include <vcl\controls.hpp> 
♦include <vcl\classes .hpp> 
♦include <vcl\forms .hpp> 
♦include <vcl\grids .hpp> 
// 

class PACKAGE TSampleCalendar : public TCustomGrid 

{ 

private: 

protected: 

public: 

__published: 

}; 

// 

♦endif 

II file CALSAMP.CPP sara simile al seguente: 

♦include <vcl\vcl.h> 
♦pragma hdrstop 
♦include "CalSamp.h" 

// 

♦pragma package(smart_mit) ; 

// 

static inline TSampleCalendar *ValidCtrCheck ( ) 

{ 

return new TSampleCalendar (NULL) ; 

} 

// 

namespace Calsamp 

{ 

void __fastcall PACKAGE Register!) 
{ 

TComponentClass classes [1] = L_classid (TSampleCalendar) } ; 

RegisterComponents ( " Samples", classes, 0); //In CLX, use a different page than "Samples" 

} 

} 

Se per creare il componente si e utilizzato il Component wizard componente, il file 
header conterra anche la dichiarazione di un nuovo costruttore e il file 
CALSAMP.CPP conterra le istruzioni iniziali di un costruttore. Se non c'e nessun 
costruttore, e possibile aggiungerlo in seguito. 
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Nelle applicazioni CLX, i nomi e le ubicazioni di alcuni file header sono differenti. 
Ad esempio, <vcl\controls .hpp> diventa <clx\qcontrols .hpp> in CLX. 



Come rendere pubbliche le proprieta ereditate 



II componente griglia astratto, TCustomGrid, e provvisto di un grande numero di 
proprieta dichiarate protected. E possibile scegliere quali di queste proprieta rendere 
disponibili per l'utente del controllo calendario. 

Per rendere disponibili agli utenti le proprieta protette ereditate dal componente, e 
necessario dichiararle nella sezione .published della dichiarazione del componente. 

Per il controllo calendario bisogna rendere pubbliche le seguenti proprieta ed eventi: 

class PACKAGE TSampleCalendar : public TCustomGrid 

{ 



.published: 
__property 

property 

__property 
__property 
__property 
__property 
__property 
__property 
__property 
__property 
__property 
__property 
__property 
__property 
__property 



Align ; 
BorderStyle ; 
Color ; 
Font ; 

GridLineWidth 
ParentColor ; 
ParentFont ; 
OnClick ; 
OnDblClick ; 
OnDragDrop ; 
OnDragOver ; 
OnEndDrag ; 
OnKeyDown ; 
OnKey Press ; 
OnKeyUp ; 



// publish properties 



// publish events 



Ci sono numerose altre proprieta che possono anche essere rese pubbliche, ma che 
non vengono utilizzate nel calendario, come Options che abilita l'utente a scegliere il 
tipo di linea da utilizzare nella griglia del disegno. 

Se si installa il componente calendario modificato nella Component palette e si 
utilizza in un'applicazione, nel calendario si troveranno molte proprieta ed eventi 
disponibili, tutti completamente funzionali. A questo punto e possibile aggiungere 
nuove possibility al proprio progetto. 



Cambiamento dei valori iniziali 



Un calendario e essenzialmente una griglia con un numero definito di righe e di 
colonne e inoltre non tutte le righe contengono sempre dei dati. Per questo motivo 
non sono state rese pubbliche le proprieta ColCount e RowCount, dal momento che e 
molto improbabile che gli utenti del calendario vogliano visualizzare piu di sette 
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giorni alia settimana. Si deve anche fissare il valore iniziale di queste proprieta, in 
modo da avere sempre sette giorni alia settimana. 

Per modificare i valori iniziali delle proprieta del componente, ridefinire il 
costruttore per impostare i valori desiderati. 

Occorre ricordarsi di aggiungere il costruttore nella parte public della dichiarazione 
della classe del componente e di scrivere il nuovo costruttore nel file header: 

class PACKAGE TSampleCalendar : public TCustomGrid 
{ 

protected: 

virtual void fastcall DrawCellfint ACol, int ARow, const Windows : :TRect SRect, 

TGridDrawState AState) ; 

public: 

fastcall TSampleCalendar (TComponent *0wner) ; // the added constructor 

}; 

Nel file CALSAMP.CPP scrivere il codice del costruttore: 

fastcall TSampleCalendar: :TSampleCalendar (TComponent *0wner) : TCustomGrid(Owner) 

{ 

ColCount = 7; 
RowCount = 7; 
FixedCols = 0; 
FixedRows = 1; 
ScrollBars = ssNone; 

Options = (Options » goRangeSelect) « goDrawFocusSelected; 

} 

void fastcall TSampleCalendar: :DrawCell (int ACol, int ARow, const Windows :: TRect 

ScARect, TGridDrawState AState) 

{ 
} 

Si pud notare che alia dichiarazione della classe e stato anche aggiunto un metodo 
DrawCell, e che nel file .CPP e stato iniziato il metodo DrawCell. Cio non e 
assolutamente necessario ora, ma se si cercasse di collaudare TSampleCalendar prima 
di ridefinire DrawCell, si incapperebbe in un errore legato alia funzione pure virtual. 
Cio e dovuto al fatto che TCustomGrid e una classe astratta.La ridefinizione di 
DrawCell viene discussa piu avanti, nella sezione "Riempimento delle celle". 

II calendario ora ha sette colonne e sette righe, di cui la riga superiore e fissa o senza 
funzionalita di scorrimento. 

Ridimensionamento delle celle 



Quando un utente o un'applicazione cambia le dimensioni di una finestra o di un 
controllo, Windows invia un messaggio di nome WM_SIZE alia finestra o al controllo 
in questione, in modo da poter sistemare qualsiasi impostazione necessaria per il 
successivo disegno nella nuova dimensione. II componente VCL puo rispondere a 
questo messaggio modificando le dimensioni delle celle in modo che tutte le celle 
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possano essere contenute entro i limiti del controllo. Per rispondere al messaggio 
WM_SIZE, e necessario aggiungere al componente un metodo per la gestione dei 
messaggi. 

La creazione di tale metodo e descritta in maniera piu dettagliata nel paragrafo 
"Creazione di nuovi gestori di messaggio" a pagina 51-6. 

In questo caso, poiche il controllo calendario deve rispondere a WM_SIZE, occorre 
aggiungere al controllo un metodo protetto di nome WMSize, quindi scrivere il 
metodo in modo tale che possa calcolare la grandezza necessaria delle celle 
permettendo alle stesse di essere visibili nella nuova dimensione: 

class PACKAGE TSampleCalendar : public TCustomGrid 
{ 

protected: 

void __fastcall WMSize (TWMSize Message) ; 

BEGIN MESSAGE MAP 

MESSAGE_HANDLER(WLSIZE, TWMSize, WMSize) 
END_MES SAGE_MAP ( TCus t omGr i d ) 

}; 

Ecco il codice per il metodo nel file CALSAMP.CPP: 

void __fastcall TSampleCalendar: iWMSize (TWMSize Message) 
{ 

int GridLines; // temporary local variable 

GridLines = 6 * GridLineWidth; // calculated combined size of all lines 

DefaultColWidth = (Message. Width - GridLines) / 7; // set new default cell width 
DefaultRowHeight = (Message. Height - GridLines) / 7; // and cell height 

} 

A questo punto, quando si ridimensiona il calendario, esso visualizza tutte le celle 
utilizzando la massima ampiezza possibile per riempire completamente il controllo. 

In CLX, le modifiche apportate alle dimensioni di una finestra o di un controllo 
vengono immediatamente notificate tramite una chiamata al metodo protetto 
BoundsChanged. II componente CLX pud rispondere a questa notifica alterando le 
dimensioni delle celle in modo che tutte le celle siano contenute entro i margini del 
controllo. 

In questo caso, il controllo calendario deve ridefinire BoundsChanged in modo tale che 
sia in grado di calcolare la grandezza delle celle necessaria aff inche esse restino 
visibili pur assumendo nuove dimensioni: 

class PACKAGE TSampleCalendar : public TCustomGrid 
{ 

protected: 

void fastcall BoundsChanged (void) ; 

}; 

Ecco il codice per il metodo nel file CALSAMP.CPP : 

void __fastcall TSampleCalendar: : BoundsChanged (void) 
{ 

int GridLines; // temporary local variable 
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GridLines = 6 * GridLineWidth; // calculated combined size of all lines 

DefaultColWidth = (Width - GridLines) II; //set new default cell width 
DefaultRowHeight = (Height - GridLines) II; II and cell height 
TCustomGrid: :BoundsChanged() ; // now call the inherited method 

} 

Riempimento delle celle 



Un controllo griglia inserisce il proprio contenuto cella per cella. Nel caso del 
calendario, cio significa calcolare quale data, se esiste, appartiene a ogni cella. II 
tracciamento predefinito delle celle della griglia viene effettuato in un metodo 
virtuale di nome DrawCell. 

Per riempire le celle della griglia, ridefinire il metodo DrawCell. 

La parte piu facile da riempire e quella delle celle dell'intestazione nella riga fissa. 
Poiche la libreria runtime contiene gia un array con i nomi abbreviati dei giorni, per il 
calendario usare quello adatto per ciascuna colonna: 

Questo e il codice per il metodo DrawCell: 

void __fastcall TSampleCalendar: : DrawCell (int ACol, int ARow, const Windows: :TRect &ARect, 
TGridDrawState AState) 

{ 

String TheText; 
int TempDay; 

if (ARow == 0) TheText = ShortDayNames [ACol + 1] ; 

else 

{ 

TheText = ""; 

TempDay = DayNum(ACol, ARow); // DayNum is defined later 

if (TempDay != -1) TheText = LntToStr (TempDay) ; 

} 

Canvas ->TextRect (ARect, ARect.Left + (Meet. Right - ARect.Left 
- Canvas->TextWidth (TheText ) ) / 2, 
ARect. Top + (ARect. Bottom - ARect. Top - Canvas ->TextHeight (TheText) ) / 2, TheText); 

} 

Registrazione della data 



Affinche il controllo del calendario risulti utile, gli utenti e le applicazioni devono 
avere un meccanismo di impostazione del giorno, del mese e dell'anno. C++Builder 
registra le date e le ore in variabili di tipo TDateTime. TDateTime e una 
rappresentazione numerica codificata della data e dell'ora, utile per la gestione 
tramite programma ma poco pratica per un utilizzo da parte di un individuo. 

E quindi possibile registrare la data in una forma codificata, consentendo l'accesso a 
tale valore in esecuzione, e fornire anche le proprieta Day, Month, e Year in modo che 
l'utente del componente calendario possa impostarle in fase di progettazione. 
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La registrazione della data e un processo composto dalle seguenti fasi: 

• Registrazione della data interna 

• Accesso a giorno, mese e anno 

• Generazione dei numeri dei giorni 

• Selezione del giorno corrente 

Registrazione della data interna 

Per registrare la data per il calendario, e necessario un membro dati privato in cui 
memorizzare la data e alcune proprieta, attive solo in esecuzione, che consentono 
l'accesso a tale data. 

1 Dichiarare un membro dati privato per memorizzare la data: 

class PACKAGE TSampleCalendar : public TCustomGrid 
{ 

private: 

TDateTime FDate; 

}; 

2 Inizializzare nel costruttore la data del membro dati: 

fastcall TSampleCalendar: :TSampleCalendar (TComponent *0wner) : TCustomGrid(Owner) 

{ 

FDate = FDate. CurrentDate ( ) ; 

} 

3 Dichiarare una proprieta di runtime per permettere l'accesso alia data codificata: 

class PACKAGE TSampleCalendar : public TCustomGrid 
{ 

public: 

__property TDateTime CalendarDate = {read=FDate, write=SetCalendarDate, nodefault}; 

}; 

E necessario un metodo per l'impostazione della data, poiche tale operazione deve 
anche aggiornare l'immagine a video del controllo. Dichiarare SetCalendarDate in 
TSampleCalendar. 

class PACKAGE TSampleCalendar : public TCustomGrid 
{ 

private: 

void __fastcall SetCalendarDate (TDateTime Value); 

}; 

Questo e il metodo SetCalendar. 

void fastcall TSampleCalendar: : SetCalendarDate (TDateTime Value) 

{ 

FDate = Value; // Set the new date value 

Refresh!); // Update the onscreen image 

} 
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Accesso a giorno, mese e anno 

Una data codificata numericamente e adatta per le applicazioni, ma e piu comodo 
lavorare con giorni, mesi e anni. E possibile preparare accessi alternativi a questi 
elementi codificati creando delle proprieta. 

Poiche ogni elemento della data (giorno, mese, anno) e un intero e poiche 
l'impostazione di ognuno richiede la ricodifica della data, e possibile evitare la 
duplicazione del codice ogni volta, condividendo il metodo per tutte e tre le 
proprieta. E possibile scrivere due metodi, uno per leggere un elemento e uno per 
scriverlo, e utilizzare questi metodi per acquisire e impostare le tre proprieta. 

Per poter accedere a giorno, mese e anno durante lo sviluppo, bisogna passare per le 
seguenti fasi: 

1 Dichiarare le tre proprieta, assegnando a ognuna un numero di indice univoco: 

class PACKAGE TSampleCalendar : public TCustomGrid 

{ 

public: 

property int Day = {read=GetDateElement , write=SetDateEleraent, index=3, 

nodefault} ; 

property int Month = {read=GetDateElement , write=SetDateElement, mdex=2, 

nodefault} ; 

property int Year = {read=GetDateEleraent , write=SetDateElement, index=l, 

nodefault} ; 

}; 

2 Dichiarare e scrivere il metodo di implementazione, impostando i diversi elementi 
per ogni valore dell'indice: 

class PACKAGE TSampleCalendar : public TCustomGrid 

{ 

private: 

int fastcall GetDateElement (int Index); // note the Index parameter 

void fastcall SetDateElement (int Index, int Value); 

}; 

Ecco i metodi GetDateElement e SetDateElement: 

int fastcall TSampleCalendar: :GetDateElement (int Index) 

{ 

unsigned short AYear, AMonth, ADay; 
int result; 

FDate.DecodeDate(&AYear, SAMonth, &ADay) ; // break encoded date into elements 

switch (Index) 

{ 

case 1: result = AYear; break; 
case 2: result = AMonth; break; 
case 3: result = ADay; break; 
default: result = -1; 

} 

return result; 

} 

void fastcall TSampleCalendar: : SetDateElement (int Index, int Value) 
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unsigned short AYear, AMonth, ADay; 
if (Value > 0) 



// all elements must be positive 



FDate.DecodeDate(&AYear, SAMonth, &ADay) ; 
switch (Index) 



// get current date elements 



case 1: AYear = Value; 
case 2: AMonth = Value; 
case 3: ADay = Value- 
default: return; 



break 
break 
break 



FDate = TDateTime (AYear, AMonth, ADay); 
Refresh () ; 



// encode the modified date 
// update the visible calendar 



Ora e possibile impostare giorno, mese e anno del calendario in fase di progetto 
utilizzando l'Object Inspector oppure in fase di esecuzione tramite programma. 
Naturalmente non e stato ancora aggiunto il codice per disegnare le date nelle celle, 
ma ora e disponibile la data desiderata. 

Generazione dei numeri dei giorni 

L'inserimento dei numeri nel calendario implica diverse considerazioni. II numero di 
giorni in un mese dipende da quale mese si considera e bisogna ricordarsi degli anni 
bisestili. Inoltre, il primo giorno del mese cade in giorni della settimana differenti, a 
seconda del mese e dell'anno. Se l'anno e bisestile, utilizzare la funzione IsLeapYear. 
Per ottenere il numero dei giorni di un mese, usare l'array MonthDays nel file header 
SysUtils. 

Quando sono note le informazioni sugli anni bisestili e sul numero di giorni in ogni 
mese, e possibile calcolare dove inserire la singola data sulla griglia. II calcolo e 
basato sul giorno della settimana con cui comincia il mese. 

Poiche per ogni cella da riempire sara necessario conoscere il numero di scostamento 
del mese, il metodo migliore e quello di calcolarne il valore ogni volta che vengono 
cambiati il mese o l'anno, e quindi fare riferimento ogni volta a tale valore. E 
possibile registrare il valore in un membro dati della classe, quindi aggiornare tale 
membro dati ogni volta che cambia la data. 

Per inserire i giorni nelle celle appropriate: 

1 Aggiungere un membro dati per l'offset del mese alia classe e un metodo che 
aggiorni il valore del membro dati: 

class PACKAGE TSampleCalendar : public TCustomGrid 

{ 

private: 

int FMonthOffset; // storage for the offset 

protected: 

virtual void __fastcall UpdateCalendar(void) ; 



}; 
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void __fastcall TSampleCalendar: :UpdateCalendar(void) 

{ 

unsigned short AYear, AMonth, ADay; 

TDateTime FirstDate; // date of first day of the month 

if ((int)FDate != 0) // only calculate offset if date is valid 

{ 

FDate. DecodeDate(&AYear, &AMonth, &ADay) ; // get elements of date 

FirstDate = TDateTime (AYear, AMonth, 1); // date of the first 

FMonthOffset = 2 - FirstDate .DayOfWeekf ) ; // generate the offset into the grid 

} 

Refresh)); // always repaint the control 

} 

2 Aggiungere istruzioni al costruttore e ai metodi SetCalendarDate e SetDateElement 
che chiamino il nuovo metodo di aggiornamento ogni volta che si cambia la data: 

__fastcall TSampleCalendar: : TSampleCalendar (TComponent *Owner) 
: TCustomGrid (Owner) 

{ 

UpdateCalendarf) ; 

} 

void __fastcall TSampleCalendar: : SetCalendarDate (TDateTime Value) 

{ 

FDate = Value; // this was already here 

UpdateCalendarf); // this previously called Refresh 

} 



void fastcall TSampleCalendar: : SetDateElement (int Index, int Value) 

{ 

FDate = TDateTime (AYear, AMonth, ADay); // this was already here 

UpdateCalendarf); // this previously called Refresh 

} 

3 Aggiungere al calendario un metodo che restituisca il numero del giorno quando 
vengono passate le coordinate della riga e della colonna di una cella: 

int fastcall TSampleCalendar: :DayNum( int ACol, int ARow) 

{ 

int result = FMonthOffset + ACol + (ARow - 1) * 7; // calculate day for this cell 

if ((result < 1) I I (result > MonthDays [isLeapYear (Year) ] [Month] ) ) 

result = -1; // return -1 if invalid 
return result; 

} 

Ricordarsi di aggiungere la dichiarazione di DayNum alia dichiarazione di tipo del 
componente. 

4 Ora che e possibile calcolare dove deve essere inserita la data, e necessario 
aggiornare DrawCell per inserire le date: 

void __fastcall TSampleCalendar: : DrawCell (int ACol, int ARow, const TRect SARect, 
TGridDrawState AState) 

{ 
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String TheText; 
int TempDay; 

if (ARow ==0) // this is the header row 

TheText = ShortDayNames [ACol + 1] ; // just use the day name 

else 
{ 

TheText = ""; // blank cell is the default 

TempDay = DayNum(ACol, ARow); // get number for this cell 

if (TempDay != -1) TheText = IntToStr (TempDay) ; // use the number if valid 

} 

Canvas->TextRect (ARect, ARect.Left + (Meet. Right - ARect.Left - 

Canvas->TextWidth (TheText ) ) / 2, 
ARect. Top + (ARect. Bottom - ARect. Top - Canvas ->TextHeight (TheText) ) / 2, TheText); 

} 

Se ora si reinstalla il componente calendario e lo si inserisce in una scheda, si possono 
vedere le informazioni corrette per il mese corrente. 

Selezione del giorno corrente 

Ora che sono stati inseriti i numeri nelle celle del calendario, sarebbe opportuno 
poter muovere la selezione evidenziando la cella contenente il giorno attuale. Per 
impostazione predefinita, la selezione inizia nella cella in alto a sinistra, pertanto 
bisogna impostare le proprieta di Row e Column sia quando si costruisce inizialmente 
il calendario sia quando si cambia la data. 

Per impostare la selezione sul giorno corrente, cambiate il metodo UpdateCalendar per 
impostare Row e Column prima di chiamare Refresh: 

void __fastcall TSampleCalendar: :UpdateCalendar(void) 

{ 

unsigned short AYear, AMonth, ADay; 
TDateTime FirstDate; 
if ((int) FDate != 0) 
{ 

I // existing statements to set FMonthOffset 

Row = (ADay - FMonthOffset) / 7 + 1; 
Col = (ADay - FMonthOffset) % 7; 

} 

Refresh!); // this is already here 

} 

Si noti che e stata riutilizzata la variabile Aday impostata in precedenza per 
decodificare la data. 



Scorrimento di mesi e anni 



Le proprieta sono utili per la gestione dei componenti, specialmente in fase di 
sviluppo. Qualche volta pero ci sono tipi di operazioni che sono comuni o naturali e 
che magari coinvolgono piu di una proprieta, tanto da suscitare la necessita di 
sviluppare un metodo per gestirli. Un esempio e la possibility di passare al 
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successive) mese nel calendario. La gestione dello scorrimento dei mesi e 1'incremento 
degli anni e semplice e molto utile per gli utilizzatori del componente. 

L'unico svantaggio nell'incapsulare le operazioni piu comuni nei metodi e che i 
metodi sono disponibili solo in fase di esecuzione. Comunque, tali operazioni sono 
piuttosto pesanti solo se effettuate ripetutamente, il che in fase di progettazione e 
molto raro. 

Per il calendario aggiungere i seguenti quattro metodi per il mese e l'anno precedente 
e successive Ognuno di questi metodi utilizza la funzione IncMonth con una leggera 
differenza per aumentare o diminuire CalendarDate, con incrementi di un mese o di 
un anno. 

void __fastcall TSampleCalendar: :NextMonth( ) 
{ 

CalendarDate = IncMonth (CalendarDate, 1); 

} 

void fastcall TSampleCalendar: :PrevMonth() 

{ 

CalendarDate = IncMonth (CalendarDate, -1); 

} 

void __fastcall TSampleCalendar: : Next Year () 
{ 

CalendarDate = lncMonth(CalendarDate, 12); 



void __fastcall TSampleCalendar: :PrevYear() 
{ 

CalendarDate = lncMonth(CalendarDate, -12); 

} 

Assicurarsi di aggiungere le dichiarazioni del nuovo metodo alia dichiarazione della 
classe. 

Ora, quando si crea un'applicazione che utilizza il componente calendario, e 
possibile implementare lo scorrimento dei mesi o degli anni. 



Scorrimento dei giorni 



Una volta noto il mese, esistono due modi ovvi per spostarsi tra i giorni. II primo e 
quello di utilizzare le frecce, l'altro e quello di usare il mouse. I componenti standard 
della griglia li utilizzano entrambi come se fossero dei clic. Cioe, un movimento con 
la freccia e trattato come se fosse un clic su una cella. 

II processo di scorrimento dei giorni e composta dalle seguenti fasi: 

• Spostamento della selezione 

• Preparazione di un evento OnChange 

• Esclusione delle celle vuote 
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II comportamento ereditato di una griglia gestisce lo spostamento della selezione in 
risposta sia ai tasti freccia sia ai clic, ma per cambiare il giorno selezionato e 
necessario modificare tale comportamento. 

Per cambiare i movimenti all'interno del calendario, ridefinire il metodo Click della 
griglia. 

Quando si ridefinisce un metodo come Click, che e vincolato alle interazioni 
dell'utente, bisogna quasi sempre includere una chiamata al metodo ereditato, cosi 
da non perdere il funzionamento predefinito. 

La procedura seguente ridefinisce il metodo Click per una griglia di calendario. 
Assicurarsi di aggiungere la dichiarazione di Click in TSampleCalendar. 

void __fastcall TSampleCalendar: :Click() 

{ 

int TempDay = DayNum(Col, Row); // get the day number for the clicked cell 

if (TempDay != -1) Day = TempDay; // change day if valid 

} 



Preparazione di un evento OnChange 



Ora che l'utente del calendario e in grado di cambiare la data, e giusto permettere alle 
applicazioni di rispondere a questi cambiamenti. 

Add an OnChange event to TSampleCalendar. 

1 Dichiarare l'evento, un data member per memorizzare l'evento e un metodo 
virtual per poterlo chiamare: 

class PACKAGE TSampleCalendar : public TCustomGrid 

{ 

private: 

TNotifyEvent FOnChange; 

protected: 

virtual void __fastcall Changed; 
__published: 

__property TNotifyEvent OnChange = {read=FOnChange, write=FOnChange} ; 

} 

2 Scrivere il metodo Change: 

void __fastcall TSampleCalendar: : Changed 

{ 

if (FOnChange != NULL) FOnChange (this) ; 

} 

3 Aggiungere le istruzioni per la chiamata a Change alia fine dei metodi 

SetCalendarDate e SetDateElement: 

void __fastcall TSampleCalendar: : SetCalendarDate (TDateTime Value) 

{ 
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FDate = Value; 
UpdateCalendarO ; 

Changed; // this is the only new statement 

} 

void fastcall TSampleCalendar: :SetDateElement (int Index, int Value) 

{ 

: // many statements setting element values 
FDate = TDateTimefAYear, Month, ADay) ; 
UpdateCalendarO ; 

Changed ; // this is new 

} 

Le applicazioni che utilizzano il componente calendario sono ora in grado di 
rispondere ai cambiamenti della data del componente collegando codice di gestione 
all'evento OnChange. 

Esclusione delle celle vuote 



Una volta scritto il calendario, l'utente puo selezionare una cella vuota, ma la data 
non cambia. E quindi utile disattivare la selezione delle celle vuote. 

Per controllare se una cella e selezionabile, ridefinire il metodo SelectCell nella griglia. 

SelectCell e una funzione che accetta come parametri una riga e una colonna e 
restituisce un valore Boolean che indica se la cella specificata e selezionabile. 

E possibile ridefinire SelectCell restituendo false se la cella non contiene una data 
valida: 

bool __fastcall TSampleCalendar: : SelectCell (mt ACol, int ARow) 
{ 

if (DayNum( ACol, ARow) == -1) return false; // -1 indicates invalid date 

else return TCustomGrid: : SelectCell (ACol, ARow); // otherwise, use inherited value 

} 

Se ora l'utente fa clic su una cella vuota o tenta di muoversi su una cella vuota con le 
frecce, il calendario lascia selezionata la cella corrente. 
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Capitolo 




Creazione di un controllo di accesso 

ai dati 

Quando si lavora con connessioni database, spesso e conveniente avere controlli 
associati ai dati. Ovvero, l'applicazione puo stabilire un collegamento tra il controllo 
e una parte del database. C++Builder include etichette, caselle di testo, caselle di 
riepilogo, caselle combinate, controlli di consultazione e griglie associati ai dati. E 
anche possibile creare propri controlli associati ai dati. Per ulteriori informazioni sui 
controlli data-aware, consultare il Capitolo 19, "Uso dei controlli dati". 

Esistono diversi livelli di associazione ai dati. II piu semplice e un controllo per 
accedere a dati in sola lettura, o data browsing, utilizzato per controllare lo stato 
attuale di un database. Piu complesso e il controllo relativo a dati che si possono 
anche modificare, o data editing, dove l'utente puo scrivere i valori da riportare nel 
database gestendo il controllo. Inoltre, si noti che il livello di interfaccia con un 
database puo variare: nel caso piu semplice si ha un collegamento con un singolo 
campo, in casi piu complessi si sviluppa un controllo che ha accesso a piu record. 

Per prima cosa il capitolo illustra il caso piu semplice, cioe la creazione di un 
controllo a sola lettura che si collega a un singolo campo in un dataset. II controllo 
specifico da utilizzare e TSampleCalendar, creato nel Capitolo 55, "Personalizzazione 
di una griglia". E anche possibile utilizzare il controllo calendario standard, 
TCalendar, presente nella pagina Samples della Component palette. 

Quindi il capitolo continua con una spiegazione di come trasformare il nuovo 
controllo per la consultazione dei dati in un controllo per X editing dei dati. 

Creazione di un controllo per I'esame dei dati 



La creazione di un controllo calendario associato ai dati, sia che sia un controllo a sola 
lettura o uno nel quale l'utente puo modificare i dati associati del dataset, coinvolge 
le seguenti operazioni: 
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• Creazione e registrazione del componente 

• Aggiunta di un datalink 

• Risposta alle modifiche dei dati 

Creazione e registrazione del componente 

La creazione di qualsiasi componente inizia sempre nello stesso modo: si deriva la 
classe di un componente, si salvano il file .CPP e .H del componente, lo si registra, lo 
si compila e lo si installa nella Component palette. Questo processo viene descritto 
nella sezione "Creazione di un nuovo componente" a pagina 45-8. 

Per questo esempio seguire la procedura generale per la creazione di un componente, 
con le seguenti specifiche: 

• Derivare una nuova classe del componente di nome TDBCalendar, discendente da 
TSampleCalendar. Capitolo 55, "Personalizzazione di una griglia", mostra come 
creare il componente TSampleCalendar. 

• Assegnare come nome DBCAL.H al file haeder e DBCAL.CPP al file .CPP. 

• Registrare TDBCalendar nella pagina Samples (o in un'altra pagina della CLX) 
della Component palette. 

Nelle applicazioni CLX i nomi e le ubicazioni di alcuni file header sono differenti. Ad 
esempio, <vcl\controls.hpp> e <clx\qcontrols.hpp> in CLX. 

II file header risultante apparira piu o meno come il seguente: 

♦lfndef DBCalH 
♦define DBCalH 

// 

♦include <vcl\sysutils .hpp> 
♦include <vcl\controls .hpp> 
♦include <vcl\classes .hpp> 
♦include <vcl\forms .hpp> 

♦include <vcl\grids .hpp> // include the Grids header 

♦include "calsamp.h" // include the header that declares TSampleCalendar 

// 

class PACKAGE TDBCalendar : public TSampleCalendar 
{ 

private: 
protected: 
public: 
__published: 

}; 

// 

♦endif 

II file .CPP risultera simile a questo: 

♦pragma link "Calsamp" // link in TSampleCalendar 

♦include <vcl\vcl.h> 
♦pragma hdrstop 
♦include "DBCal.h" 
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// 

ipragma package ( smart_mit ) ; 

// 

static inline TDBCalendar *ValidCtrCheck( ) 
{ 

return new TDBCalendar (NULL) ; 

} 

// 

namespace Dbcal 
{ 

void __fastcall PACKAGE Register!) 
{ 

TComponentClass classes [1] = L_classid(TDBCalendar) } ; 

RegisterComponents ( " Samples", classes, 0); //Use different page in CLX applications 

} 

} 

Se si e utilizzato il wizard Component per iniziare la creazione del componente 
TDBCalendar, il file header conterra il costruttore gia dichiarato e il file .CPP avra la 
definizione del costruttore. 

Ora e possibile trasformare il nuovo componente in un visualizzatore di dati. 

Costruzione del controllo a sola lettura 



Dal momento che questo calendario sara a sola lettura, ha senso definire il controllo 
stesso come a sola lettura, in modo che gli utenti non possano effettuarvi 
cambiamenti e ritrovarli nei dati del database. 

Definire un calendario a sola lettura implica: 

• Aggiunta della proprieta ReadOnly. 

• Permettere gli aggiornamenti necessari. 

Si noti che, iniziando con il componente TCalendar della pagina Samples di 
C++Builder, anziche con TSampleCalendar, e gia presente la proprieta ReadOnly , 
quindi questi passi possono essere saltati. 

Aggiunta della proprieta ReadOnly 

Aggiungendo una proprieta ReadOnly , e possibile introdurre un metodo che 
garantisca che il controllo sia accessibile in sola lettura in fase di sviluppo. Quando 
questa proprieta e impostata a true, e possibile rendere non selezionabili tutte le celle 
incluse nel controllo. 

1 Aggiungere al file DBCAL.H la dichiarazione della proprieta e un membro dati 
private per registrarne il valore: 

class PACKAGE TDBCalendar : public TSampleCalendar 
{ 

private: 

bool FReadOnly; // field for internal storage 

protected: 
public: 
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virtual fastcall TDBCalendar(TComponent* Owner); 

published: 

__property Readonly = {read=FReadOnly , write=FReadOnly, default=true} ; 

}; 

2 Scrivere il costruttore nel file DBCAL.CPP: 

virtual __fastcall TDBCalendar: :TDBCalendar(TComponent* Owner) : 
TSampleCalendar (Owner) 

{ 

FReadOnly = true; // sets the default value 

} 

3 Ridefinire il metodo SelectCell per disabilitare la selezione se il controllo e a sola 
lettura. L'utilizzo di SelectCell viene illustrato in "Esclusione delle celle vuote" a 
pagina 55-14. 

bool __fastcall TDBCalendar: : SelectCell (long ACol, long ARow) 
{ 

if (FReadOnly) return false; // can't select if read only 

return TSampleCalendar: :SelectCell (ACol, ARow); // otherwise, use inherited method 

} 

Bisogna ricordarsi di aggiungere la dichiarazione SelectCell alia dichiarazione della 
classe di TDBCalendar. 

Se si aggiunge il calendario a una scheda, il componente ignora i clic e le pressioni dei 
tasti. Commette un errore anche nell'aggiornare la posizione selezionata quando si 
cambia la data. 

Permettere gli aggiornamenti necessari 

II nuovo calendario utilizza il metodo SelectCell per tutti i tipi di cambiamenti, incluse 
le impostazioni delle proprieta Row e Col. II metodo UpdateCalendar imposta Row e 
Col ogni volta che viene cambiata la data, ma dal momento che SelectCell non 
permette i cambiamenti, la selezione rimane dov'era anche se la data cambia. 

Per aggirare questa proibizione assoluta sui cambiamenti, e possibile aggiungere un 
flag interno di tipo Boolean al calendario e permettere i cambiamenti quando questo 
flag e impostato a true: 

class PACKAGE TDBCalendar : public TSampleCalendar 
{ 

private: 

bool FUpdating; // private flag for internal use 

protected: 

virtual bool __fastcall SelectCell (long ACol, long ARow); 
public: 

virtual void __fastcall UpdateCalendar)); 

}; 

bool __fastcall TDBCalendar: : SelectCell (long ACol, long ARow) 
{ 

if (IFUpdating && FReadOnly) return false; // can't select if read only 
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return TSampleCalendar: :SelectCell (ACol, ARow) ; 



// otherwise, use inherited method 



void fastcall TDBCalendar: :UpdateCalendar ( ) 



FUpdating=true; 
try 



// set flag to allow updates 



TSampleCalendar: :UpdateCalendar ( ) ; 



// update as usual 



} 

catch) . . . ) 

{ 

FUpdating = false; 
throw; 

} 

FUpdating = false; // always clear the flag 



II calendario non permette ancora i cambiamenti da parte dell'utente, ma ora riflette 
correttamente i cambiamenti della data effettuati cambiando le proprieta. Ora che si 
ha un corretto controllo a sola lettura, e possibile aggiungere la connessione alia base 
dati. 



II collegamento tra un controllo e un database e gestito da una classe chiamata 
datalink. La classe per il collegamento dati che collega un controllo con un singolo 
membro dati di un database e TFieldDataLink. Ci sono inoltre collegamenti di dati per 
intere tabelle. 

Un controllo associato ai dati possiede la sua classe datalink. Questo significa che il 
controllo ha la responsabilita della costruzione e della distruzione del datalink. Per 
maggiori informazioni sulla gestione delle classi possedute, consultare il Capitolo 54, 
"Creazione di un controllo grafico". 

Per creare un datalink come una classe posseduta, effettuare queste tre operazioni: 

1 Dichiarazione del membro dati. 

2 Dichiarzione delle proprieta di accesso. 

3 Inizializzazione del datalink. 

Dichiarazione del membro dati 

Come spiegato nella "Dichiarazione dei membri dati della classe" a pagina 54-6 un 
componente ha bisogno di un membro dati per ciascuna delle classi che possiede. In 
questo caso, per il collegamento dei dati, il calendario ha bisogno di un membro dati 
di tipo TFieldDataLink. 

Dichiarare un campo per il collegamento dei dati nel calendario: 

class PACKAGE TDBCalendar : public TSampleCalendar 
{ 

private: 



Aggiunta di un datalink 



Creazione di un controllo di accesso ai dati 56-5 



Creazione di un controllo per I'esame dei dati 

TFieldDataLink *FDataLink; 

}; 

Prima di compilare l'applicazione, e necessario includere i file DB.HPP e 
DBTABLES.HPP nel file DBCAL.H: 

♦include <DB.hpp> 
♦include <DBTables .hpp> 

Dichiarzione delle proprieta di accesso 

Ogni controllo data-aware ha una proprieta DataSource che specifica quale classe 
datasource nell'applicazione fornisce i dati al controllo. Inoltre, un controllo che 
accede ad un singolo campo ha bisogno della proprieta DataField per specificare quel 
campo nella sorgente dati. 

A differenza di quanto visto nell'esempio relativo alle classi possedute riportato nel 
Capitolo 54, "Creazione di un controllo grafico", le proprieta di accesso trattate 
nell'esempio non consentono di accedere alle classi possedute, ma alle proprieta 
corrispondenti nella classe posseduta. In pratica, bisogna costruire proprieta che 
abilitano il controllo e il relativo collegamenti a condividere la stessa sorgente dati e 
lo stesso campo. 

Dichiarare le proprieta DataSource e DataField e i rispettivi metodi di 
implementazione, quindi scrivere i metodi come metodi "pass-through" per arrivare 
alle proprieta corrispondenti della classe datalink: 

Un esempio di dichiarazione delle proprieta di accesso 

class PACKAGE TDBCalendar : public TSampleCalendar 
{ 

private: 

AnsiString __fastcall GetDataField( ) ; // methods are private 

TDataSource *__fastcall GetDataSource ( ) ; // returns name of data field 

void __fastcall SetDataField(AnsiString Value); // returns reference to data 

// source 

void __fastcall SetDataSource (TDataSource *Value) ; // assigns name of data field 

published: // make properties available at design time 

property AnsiString DataField = {read=GetDataField, write=SetDataField, nodefault}; 

__property TDataSource * DataSource = {read=GetDataSource, write=SetDataSource, 
nodefault} ; 



AnsiString __fastcall TDBCalendar: :GetDataField( ) 
return FDataLink->FielcWame; 

TDataSource *__fastcall TDBCalendar: : GetDataSource () 
return FDataLink->DataSource; 
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void __fastcall TDBCalendar: :SetDataField(AnsiString Value) 

{ 

FDataLink->FieldName = Value; 

} 

void __fastcall TDBCalendar: : SetDataSource (TDataSource *Value) 
{ 

if (Value != NULL) 

Value->FreeNotification(this) ; 
FDataLink->DataSource = Value; 

} 

Ora che sono stati stabiliti i collegamenti tra il calendario e il relativo datalink, c'e il 
passo piu importante. E necessario costruire una classe datalink quando il controllo 
calendario viene generato e distruggere il datalink prima della distruzione del 
calendario. 

Inizializzazione del datalink 

Un controllo associato ai dati deve poter accedere al proprio datalink finche esiste e 
quindi deve costruire l'oggetto datalink all'interno del proprio costruttore e 
distruggerlo prima di essere a sua volta distrutto. 

Ridefinire il costruttore e il distruttore del calendario: 

class PACKAGE TDBCalendar : public TSampleCalendar 

{ 

public: 

virtual fastcall TDBCalendar (TComponent *0wner) ; 

__fastcall ~TDBCalendar(); 

}; 

__fastcall TDBCalendar: :TDBCalendar(TComponent* Owner) : TSampleCalendar (Owner) 

{ 

FReadOnly = true; 

FDataLink = new TFieldDataLink( ) ; 

FDataLink->Control = this; 

} 

__fastcall TDBCalendar: : -TDBCalendar)) 

{ 

FDataLink->Control = NULL; 
FDataLink->OnUpdateData = NULL; 
delete FDataLink; 

} 

A questo punto e stato completato il collegamento ai dati, ma non e stato ancora 
specificato al controllo quali dati deve leggere dal campo collegato. La prossima 
sezione spiega come fare. 

Risposta alle modifiche dei dati 



Una volta che un controllo e stato dotato di un proprio datalink e di proprieta che 
consentono di specificare la sorgente dati e il campo dati, deve poter rispondere ai 
cambiamenti dei dati in tale campo, sia dovuti a uno spostamento in un record 
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diverso sia per reagire a un cambiamento effettuato sul valore del campo all'interno 
della base dati. 

Tutte le classi datalink dispongono di eventi chiamati OnDataChange. Quando il data- 
sorce indica un cambiamento nei propri dati, l'oggetto datalink chiama il gestore di 
evento collegato al proprio evento OnDataChange. 

Per aggiornare un controllo in risposta a un cambiamento di dati, si aggiunge un 
gestore all'evento OnDataChange del datalink. 

In questo caso, si puo aggiungere un metodo al calendario, quindi indicarlo come il 
gestore per l'evento OnDataChange del datalink. 

Dichiarare e implementare il metodo DataChange, quindi assegnarlo all'evento 
OnDataChange del datalink nel costruttore. Nel distruttore, prima di distruggere 
l'oggetto, sconnettere il gestore OnDataChange. 

class PACKAGE TDBCalendar : public TSampleCalendar 

{ 

private: 

void __fastcall DataChange (TObject * Sender ) ; 

}; 

void __fastcall TDBCalendar: : DataChange ( TObject* Sender) 

{ 

if (FDataLink->Field == NULL) // if no field is assigned . . . 

CalendarDate = 0; // ...set to invalid date 

else CalendarDate = FDataLmk->Field->AsDateTime; // otherwise, set to new data 

} 

__fastcall TDBCalendar: :TDBCalendar(TComponent* Owner) : TSampleCalendar (AOwner) 
{ 

FReadOnly = true; 

FDataLink = new TFieldDataLink( ) ; // construct the datalink object 

FDataLink->Control = this; 

FDataLink->OnDataChange = DataChange; // attach the handler 

} 

__fastcall TDBCalendar: : -TDBCalendar)) 

{ 

FDataLink->Control = NULL; 
FDataLink->OnUpdateData = NULL; 

FDataLink->OnDataChange = NULL; // detach the handler before... 

delete FDataLink; // ...destroying the datalink object 

} 

Ora il controllo per l'esame dei dati e pronto. 

Creazione di un controllo per I'editing dei dati 



Quando si crea un controllo per la modifica di dati si crea e registra il componente e 
si aggiunge il datalink esattamente nello stesso modo utilizzato per un controllo per 
la consultazione dei dati. In modo analogo, occorre rispondere anche alle modifiche 
apportate ai dati nel campo associato ma occorre gestire qualche problema ulteriore. 
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Per esempio, e probabile che il controllo debba risponda sia agli eventi della tastiera 
sia a quelli del mouse. II controllo deve rispondere quando l'utente ne modifica i 
contenuti. Quando l'utente esce dal controllo, le modifiche apportate nel controllo 
dovranno essere riportate nel dataset. 

II controllo per la modifica di dati descritto di seguito e lo stesso controllo calendario 
descritto nella prima parte del capitolo. II controllo viene modificato in modo da 
poter modificare e visualizzare i dati nel campo collegato. 

La modifica di un controllo esistente per trasformarlo in un controllo per la modifica 
di dati comporta le seguenti operazioni: 

• Modifica del valore predefinito di FReadOnly. 

• Gestione dei messaggi mouse-down e key-down. 

• Modifica della classe datalink del campo. 

• Modifica del metodo Change. 

• Aggiornamento del dataset. 

Modifica del valore predefinito di FReadOnly 



Poiche questo e un controllo per la modifica di dati, per impostazione predefinita la 
proprieta ReadOnly dovrebbe essere impostata a false. Per rendere false la proprieta 
ReadOnly, modificare nel costruttore il valore FReadOnly: 

__fastcall TDBCalendar: :TDBCalendar (TComponent* Owner) : TSampleCalendar (Owner) 
{ 

FReadOnly = false; // set the default value 

} 

Gestione dei messaggi mouse-down e key-down 



Quando l'utente del controllo comincia ad interagire con esso, il controllo riceve o un 
messaggio mouse-down (WM_LBUTTONDOWN, WM_MBUTTONDOWN, o 
WM_RB UTTONDOWN) oppure un messaggio key-down (WM_KEYDOWN) da 
Windows. Per fare in modo che un controllo risponda a questi messaggi, si devono 
scrivere appositi gestori di messaggio. 

• Risposta ai messaggi mouse-down 

• Risposta a messaggi key-down 

Nel caso si usi CLX, la notifica proviene dal sistema operativo sotto forma di eventi 
di sistema. Per informazioni sulla scrittura di componenti che rispondono a aventi di 
sistema e di widget, consultare "Risposta alle notifiche di sistema utilizzando la 
CLX" a pagina 51-11. 

Risposta ai messaggi mouse-down 

Un metodo MouseDown e un metodo protetto dell'evento OnMouseDown di un 
controllo. II controllo stesso chiama MouseDown in risposta a un messaggio mouse- 
down di Windows. Quando si ridefinisce il metodo MouseDown ereditato, si pud 
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includere codice che fornisce altre risposte oltre a quella di chiamata dell'evento 

OnMouseDown. 

Per ridefinire MouseDown, aggiungere un metodo MouseDown alia classe 
TDBCalendar. 

class PACKAGE TDBCalendar : public TSampleCalendar 

{ 

protected: 

virtual void __fastcall MouseDown (TMouseButton Button, TShiftState Shift, int X, 
int Y) ; 

}; 

Scrivere il metodo MouseDown nel file .CPP: 

void __fastcall TDBCalendar: :MouseDown (TMouseButton Button, TShiftState Shift, int X, 
int Y) 

{ 

TMouseEvent MyMouseDown; // declare event type 

if (IFReadOnly && FDataLink->Edit ( ) ) // if the field can be edited 

TSampleCalendar: :MouseDown (Button, Shift, X, Y) ; // call the inherited MouseDown 
else 

{ 

MyMouseDown = OnMouseDown; // assign OnMouseDown event 

if (MyMouseDown != NULL) MyMouseDown (this, Button, // execute code in the... 

Shift, X, Y) ; // ...OnMouseDown event handler 



Quando MouseDown risponde a un messaggio del mouse, il metodo MouseDown 
ereditato viene chiamato solamente se la proprieta ReadOnly del controllo e false e 
l'oggetto datalink e in modalita modifica, il che significa che il campo pud essere 
modificato. Se il campo non pud essere modificato, viene eseguito il codice inserito 
dal programmatore nel gestore evento OnMouseDown, se ne esiste uno. 



Risposta a messaggi key-down 

II metodo KeyDown e un metodo protetto per l'evento OnKeyDown di un controllo. II 
controllo stesso chiama KeyDown in risposta a un messaggio key-down di Windows. 
Quando si ridefinisce il metodo MouseDown ereditato, si puo includere del codice che 
fornisca altre risposte oltre a quella di chiamata dell'evento OnMouseDown. 

Per ridefinire KeyDown, seguire questa procedura: 

1 Aggiungere un metodo KeyDown alia classe TDBCalendar: 

class PACKAGE TDBCalendar : public TSampleCalendar 

{ 

protected: 

virtual void __fastcall KeyDown (unsigned short &Key, TShiftState Shift); 

}; 

2 Scrivere il metodo KeyDown nel file .CPP: 
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void __fastcall TDBCalendar: :KeyDown (unsigned short &Key, TShiftState Shift) 

{ 

TKeyEvent MyKeyDown; // declare event type 

Set<unsigned short, 0,8> keySet; 

keyset = keySet « VKJJP « VK_D0WN « VK_LEFT // assign virtual keys to set 

« VK_RIGHT « VK_END « VK_H0ME « VK_PRI0R « VK_NEXT ; 
if (IFReadOnly && // if control is not read only... 

(keySet .Contains (Key) ) && // ...and key is in the set... 

FDataLink->Edit ( ) ) // ...and field is in edit mode 

{ 

TCustomGrid: :KeyDown (Key , Shift); // call the inherited KeyDown method 

} 

else 
{ 

MyKeyDown = OnKeyDown; // assign OnKeyDown event 

if (MyKeyDown != NULL) MyKeyDown (this , Key , Shift ) ; // execute code in... 
} // ...OnKeyDown event handler 

} 

Quando KeyDown risponde a un messaggio key-down, il metodo KeyDown ereditato 
viene chiamato solamente se la proprieta ReadOnly del controllo e false, il tasto 
premuto e uno dei tasti di controllo del cursore e l'oggetto del datalink e in modalita 
modifica, il che significa che il campo puo essere modificato. Se il campo non puo 
essere modificato, viene eseguito il codice inserito dal programmatore nel gestore di 
evento OnKeyDown, se ne esiste uno. 



Modifica della classe datalink del campo 



Ci sono due tipi di modifiche dei dati: 

• Una modifica di un valore di campo che deve essere riportata nel controllo 
associato ai dati. 

• Una modifica del controllo associato ai dati che deve essere riportata nel valore di 
campo. 

II componente TDBCalendar ha gia un metodo DataChange che gestisce una modifica 
del valore del campo nel dataset assegnando tale valore alia proprieta CalendarDate. II 
metodo DataChange e il gestore dell'evento OnDataChange. Quindi, il componente 
calendario puo gestire il primo tipo di modifica dei dati. 

Analogamente, anche la classe datalink del campo ha un evento OnUpdateData che si 
verifica quando l'utente del controllo modifica i contenuti del controllo data-aware. II 
controllo calendario ha un metodo UpdateData che diviene il gestore dell'evento 
OnllpdateData. UpdateData assegna il valore modificato del controllo data-aware al 
campo data-link. 

1 Per riflettere una modifica effettuata al valore nel calendario nel valore del campo, 
aggiungere un metodo UpdateData alia sezione private del componente 
calendario: 

class PACKAGE TDBCalendar : public TSampleCalendar 

{ 

private: 
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void __fastcall UpdateData (TObject * Sender ) ; 

}; 

2 Scrivere il metodo UpdateData nel file .CPP: 

void __fastcall TDBCalendar: :UpdateData( TObject* Sender) 

{ 

FDataLink->Field->AsDateTime = CalendarDate; // set field link to calendar date 

} 

3 All'interno del costruttore per TDBCalendar assegnare il metodo UpdateData 
all'evento OnUpdateData: 

__fastcall TDBCalendar: :TDBCalendar(TComponent* Owner) 
: TSampleCalendar (Owner) 

{ 

FDataLink = new TFieldDataLink( ) ; // this was already here 

FDataLink->OnDataChange = DataChange; // this was here too 

FDataLink->OnUpdateData = UpdateData; // assign UpdateData to the OnUpdateData event 

} 

Modifica del metodo Change 



II metodo Change di TDBCalendar viene chiamato ogni qualvolta si imposta un nuovo 
valore della data. Change chiama il gestore di evento OnChange, se ne esiste uno. 
L'utente del componente puo scrivere codice nel gestore di evento OnChange per 
rispondere alle modifiche della data. 

Quando varia la data del calendario, ai dataset associati si dovrebbe notificare la 
variazione. Questo si puo fare ridefinendo il metodo Change e aggiungendo 
un'istruzione ulteriore. Questi sono i passi da seguire: 

1 Aggiungere un nuovo metodo Change al componente TDBCalendar. 

class PACKAGE TDBCalendar : public TSampleCalendar 

{ 

protected: 

virtual void __fastcall Changed; 

}; 

2 Scrivere il metodo Change, chiamando il metodo Modified che informa il dataset 
che i dati sono stati modificati, quindi chiamare il metodo Change ereditato: 

void fastcall TDBCalendar: : Changed 

{ 

if (FDataLink != NULL) 

FDataLink- >Modified( ) ; // call the Modified method 

TSampleCalendar: : Change () ; // call the inherited Change method 

} 
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Aggiornamento del dataset 



Finora, una modifica all'interno del controllo data-aware ha modificato valori nella 
classe datalink del campo. II passo finale della creazione di un controllo modifica dati 
e quello di aggiornare il dataset col nuovo valore. L'aggiornamento dovrebbe essere 
effettuato quando chi ha modificato il valore nel controllo associato ai dati esce dal 
controllo facendo clic esternamente al controllo o premendo il tasto Tab. Questo 
processo funziona in modo diverso nella VCL e nella CLX. 

Nella VCL sono definiti vari ID per il controllo dei messaggi relativi alle operazioni 
sui controlli. Per esempio, il messaggio CM_EXIT viene trasmesso al controllo 
quando l'utente ne esce. Si possono scrivere gestori di messaggi che rispondono al 
messaggio. In questo caso, quando l'utente esce dal controllo, il metodo CMExit, il 
gestore del messaggio CM_EXIT, risponde aggiornando il record nel dataset coi 
valori modificati nella classe campo datalink. Per maggiori informazioni sui gestori 
di messaggio, consultare il Capitolo 51, "Gestione dei messaggi e delle notifiche di 
sistema". 

Per aggiornare il dataset all'interno di un gestore messaggi: 

1 Aggiungere il gestore messaggio al componente TDBCalendar. 

class PACKAGE TDBCalendar : public TSampleCalendar 
{ 

private: 

void __fastcall CMExit (TWMNoParams Message); 

BEGIN J4ESSAGEJ4AP 

MESSAGE_HANDLER ( CM_EXIT , TWMNoParams, CMExit) 
END_MESSAGE_MAP 

}; 

2 Scrivere il codice nel file .CPP in modo che somigli al seguente: 

void __fastcall TDBCalendar: : CMExit (TWMNoParams &Message) 
{ 

try 

{ 

FDataLink.UpdateRecordf ) ; // tell data link to update database 

} 

catch) . . . ) 
{ 

SetFocusO; // if it failed, don't let focus leave 

throw; 

} 

} 

Nella CLX, TWidgetControl ha un metodo protetto DoExit che viene chiamato quando 
il fuoco viene spostato via dal controllo. Questo metodo chiama il gestore di evento 
deU'evento OnExit. E possibile ridefinire questo metodo per aggiornare il record nel 
dataset prima di generare il gestore di evento OnExit. 

Per aggiornare il dataset quando l'utente si sposta dal controllo, fare quanto segue: 
1 Aggiungere la direttiva override al metodo DoExit del componente TDBCalendar. 
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class PACKAGE TDBCalendar : public TSampleCalendar 

{ 

private: 

DYNAMIC void __fastcall DoExit (void) ; 

}; 

2 Scrivere il codice nel file .CPP in modo che somigli al seguente: 

void __fastcall TDBCalendar: : DoExit (void) 

{ 

try 
{ 

FDataLink.UpdateRecordO ; // tell data link to update database 

} 

catch ( . . . ) 

{ 

SetFocusO; // if it failed, don't let focus leave 

throw; 

} 

TCustomGrid: :DoExit ( ) ; // let the inherited method generate an OnExit event 
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Trasformazione di una finestra di 
dialogo in un componente 

A volte potrebbe risultare utile trasformare una finestra di dialogo usata di frequente 
in un componente da aggiungere alia Component palette. I componenti finestra di 
dialogo funzioneranno esattamente come i componenti standard delle finestre di 
dialogo comuni. Lo scopo e quello di creare un semplice componente che possa 
essere aggiunto a un progetto e per il quale sia possibile impostarne le proprieta in 
fase di progettazione. 

La trasformazione di una finestra di dialogo in un componente richiede le seguenti 
operazioni: 

1 Definizione dell'interfaccia del componente. 

2 Creazione e registrazione del componente 

3 Creazione dell'interfaccia del componente 

4 Verifica del componente 

II componente "wrapper" di C++Builder associato alia finestra di dialogo, crea ed 
esegue la finestra di dialogo durante l'esecuzione, passando i dati specificati 
dall'utente. II componente finestra di dialogo risulta pertanto riutilizzabile e 
Personalizzazione. 

Questo capitolo descrive come creare un componente contenitore (wrapper) che 
contiene la finestra About Box fornita nell'Object Repository di C++Builder. 

Copiare i file ABOUT.H, ABOUT.CPP e ABOUT. DFM nella directory di lavoro. 
Aggiungere ABOUT.CPP al progetto in modo da creare un file ABOUT.OBJ quando 
si costruisce il componente contenitore. 

Non ci sono considerazioni speciali da fare per la progettazione di una finestra di 
dialogo che deve essere inglobata in un componente. Quasi tutte le schede possono 
operare come una finestra di dialogo in questo contesto. 
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Definizione dell'interfaccia del componente. 



Prima di creare il componente per la finestra di dialogo, occorre decidere come 
svilupparlo in modo da poterlo utilizzare. E possibile creare un'interfaccia tra la 
finestra di dialogo e le applicazioni che la utilizzano. 

Per esempio, si osservino le proprieta dei componenti di una comune finestra di 
dialogo. E possibile notare che consentono agli sviluppatori di impostare lo stato 
iniziale della finestra di dialogo, come il titolo e l'impostazione iniziale dei controlli, 
e, una volta chiusa la finestra di dialogo, di rileggere tutte le informazioni necessarie. 
Non ci sono interazioni dirette con i singoli controlli nella finestra di dialogo, ma solo 
con le proprieta nel componente contenitore. 

L'interfaccia deve inoltre contenere informazioni sufficienti affinche la scheda della 
finestra di dialogo possa apparire nella modalita specificata dallo sviluppatore e 
restituisca ogni informazione richiesta dall'applicazione. Si puo pensare alle 
proprieta incapsulate nel componente contenitore come a dati persistenti per una 
finestra di dialogo transiente. 

La finestra About non deve restituire alcuna informazione, cosi le proprieta del 
contenitore devono contenere solo le informazioni necessarie per visualizzare 
correttamente la finestra. Poiche ci sono quattro campi separati nella finestra About 
che possono essere modificati dalle applicazioni, si forniranno, per questi, quattro 
proprieta di tipo stringa. 

Creazione e registrazione del componente 



La creazione di qualsiasi componente inizia sempre nello stesso modo: si deriva la 
classe di un componente, si salvano il file .CPP e .H del componente, lo si registra, lo 
si compila e lo si installa nella component palette. Questo processo viene descritto 
nella sezione "Creazione di un nuovo componente" a pagina 45-8. 

Per questo esempio e necessario seguire la procedura generale per la creazione di un 
componente, con le seguenti specifiche: 

• Derivare un nuovo tipo di componente chiamato TAboutBoxDlg, discendente da 
TComponent. 

• Chiamare i file unit del componente ABOUTDLG.H e ABBOUTDLG.CPP. 

• Registrare TAboutBoxDlg nella pagina Sample della Component palette. 
II file .HPP risultante dovrebbe essere simile al seguente: 

♦ifndef AboutDlgH 
♦define AboutDlgH 

// 

♦include <vcl\sysutils .hpp> 
♦include <vcl\controls .hpp> 
♦include <vcl\classes .hpp> 
♦include <vcl\forms .hpp> 
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class PACKAGE TAboutBoxDlg : public TComponent 
{ 

private: 
protected: 
public: 
__published: 

}; 

// 

♦endif 

II file .CPP della unit sara simile al seguente: 

♦include <vcl\vcl.h> 
♦pragma hdrstop 
♦include "AboutDlg.h" 

// 

♦pragma package ( smart_init ) ; 

// 

static inline TAboutBoxDlg *ValidCtrCheck ( ) 
{ 

return new TAboutBoxDlg (NULL) ; 

} 

// 

namespace AboutDlg { 
{ 

void __fastcall PACKAGE Register () 

{ 

TComponentClass classes [1] = {__classid(TAboutBoxDlg) '. 
RegisterComponents ( "Samples", classes, 0); 



Se e stato utilizzato il wizard Component per inizializzare questo componente, a 
TAboutDlg verra aggiunto anche un costruttore. 

Nelle applicazioni CLX i nomi e le ubicazioni di alcuni file header sono differenti. Ad 
esempio, <vcl\controls.hpp> e <clx\qcontrols.hpp> in CLX. 

In questa fase il nuovo componente ha solamente le capacita intrinseche ed ereditate 
da TComponent. E il piu semplice componente non visuale. Nella sezione successiva si 
creera l'interfaccia tra il componente e la finestra di dialogo. 



Creazione dell'interfaccia del componente 



Queste sono le operazioni da svolgere per creare l'interfaccia del componente: 

1 Inclusione dei file unit della scheda. 

2 Aggiunta delle proprieta di interfaccia. 

3 Aggiunta del metodo Execute. 
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Inclusione dei file unit della scheda 



Per inizializzare il proprio componente wrapper e visualizzare la finestra di dialogo 
inclusa, e necessario aggiungere i file della scheda al progetto. 

Includere ABOUT.H e il collegamento ad ABOUT.OBJ nel file header del 
componente: 

# include " About. h" 
ipragma link "About. obj" 

II file header della scheda dichiara sempre un'istanza della classe della scheda. Nel 
caso della finestra About, la classe della scheda e TAboutBox e il file ABOUT.H 
include quanto segue: 

extern TAboutBox *AboutBox; 

Aggiunta delle proprieta di interfaccia 



Prima di procedere, bisogna decidere quali sono le proprieta necessarie al contenitore 
affinche gli sviluppatori possano utilizzare la finestra di dialogo come componente 
nelle applicazioni. Per ottenere cio, si possono aggiungere le dichiarazioni per queste 
proprieta nella dichiarazione del componente. 

Le proprieta nei componenti contenitore sono qualcosa di piu semplice delle 
proprieta che si potrebbero creare scrivendo un semplice componente. Ricordarsi 
che, in questo caso, si stanno creando alcuni dati persistenti che il contenitore puo 
passare alia finestra di dialogo e ricevere da essa. Inserendo questi dati sotto forma di 
proprieta, si consente agli sviluppatori di impostare i dati in fase di progetto, in 
modo che il contenitore li possa passare alia finestra di dialogo in fase di esecuzione. 

La dichiarazione di una proprieta di interfaccia richiede due aggiunte alia 
dichiarazione della classe del componente: 

• Un membro dati privato, cioe la variabile che il contenitore usa per registrare il 
valore della proprieta 

• La dichiarazione published stessa della proprieta, che specifica il nome della 
proprieta e indica quale membro dati utilizzare per la registrazione. 

Le proprieta di interfaccia di questo tipo non necessitano di metodi di accesso. 
Utilizzano un accesso diretto ai propri dati registrati. Per convenzione, il membro 
dati che contiene il valore di proprieta ha lo stesso nome della proprieta, ma 
preceduto dalla lettera F. II membro dati e la proprieta devono essere dello stesso 
tipo. 

Per esempio, per dichiarare una proprieta di interfaccia di tipo integer di nome Year, 
dichiararla come segue: 

class PACKAGE TWrapper : public TComponent 
{ 

private: 

int FYear; // data member to hold the Year-property data 

protected: 
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public: 
__published: 

__property int Year = {read=FYear, write=FYear} ; // property matched with storage 

}; 

Per la finestra About servono quattro proprieta di tipo string, rispettivamente per il 
nome del prodotto, l'informazione sulla versione, l'informazione sul copyright e un 
eventuale commento. II file ABOUTDLG.H apparira ora in questo modo: 

class PACKAGE TAboutBoxDlg : public TComponent 

{ 

private: 

int FYear; 

String FProductName, FVersion, FCopyright, FComments; 
protected: 
public: 
__published: 

__property int Year = {read=FYear, write=FYear} ; 

property String ProductName = {read=FProductNarae, write=FProductName} ; 

__property String Version = {read=FVersion, write=FVersion} ; 
__property String Copyright = {read=FCopyright , write=FCopyright } ; 
__property String Comments = {read=FComments, write=FComments } ; 

}; 

Quando si installa il componente nella component Palette e lo si colloca su una 
scheda, sara possibile impostarne le proprieta, e questi valori saranno 
automaticamente inseriti nella scheda. II contenitore potra quindi utilizzare questi 
valori quando esegue la finestra di dialogo inglobata. 

Aggiunta del metodo Execute 



La parte finale del componente interfaccia e un metodo per aprire la finestra di 
dialogo e restituire un risultato quando viene chiusa. Come con i componenti 
finestra di dialogo comune, e possibile utilizzare una funzione booleana di nome 
Execute che restituisce true se l'utente fa clic su OK, oppure false se l'utente annulla 
la finestra di dialogo. 

La dichiarazione del metodo Execute e sempre simile alia seguente: 

class PACKAGE TMyWrapper : public TComponent 
{ 

public: 

bool __fastcall Executed; 

}; 

L'implementazione minima di Execute deve costruire la finestra di dialogo, mostrarla 
come una finestra di dialogo modale e restituire true o false, a seconda del valore 
restituito da ShowModal. 

Questo e il metodo Execute per una finestra di dialogo di tipo TMyDialogBox: 

bool __fastcall TMyWrapper: : Executed 

{ 
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DialogBox = new TMyDialogBox (Application) ; // construct the form 

bool Result; 
try 
{ 

Result = (DialogBox->ShowModal() IDOK); // execute; set result based on how closed 



catch ( . . . ) 

{ 

Result = false; 



// if it fails, set Result to false 



DialogBox->Free { 



// dispose of form 



In pratica, ci sara piu codice all'interno di exception handler. In particolare, prima 
della chiamata ShowModal, il contenitore imposta alcune proprieta della finestra di 
dialogo basandosi sulle proprieta di interfaccia del componente contenitore. Al 
ritorno da ShowModal, e probabile che il contenitore imposti alcune proprieta di 
interfaccia in base al risultato dell'esecuzione della finestra di dialogo. 

Nel caso della finestra About, sara necessario utilizzare le quattro proprieta di 
interfaccia del componente contenitore per impostare il contenuto delle etichette 
nella finestra della scheda About. Poiche la finestra About non restituisce nessuna 
informazione all'applicazione, non c'e la necessita di fare qualcosa dopo la chiamata 
a ShowModal. Scrivere il metodo Execute del wrapper della finestra About in modo 
che il file ABOUTDLG.CPP sia simile al seguente: 



bool __fastcall TAboutBoxDlg: :Execute() 

{ 

AboutBox = new TAboutBox(Application) ; 

bool Result; 

try 

{ 

if (ProductName == "") 

ProductName = Application->Title; 
AboutBox->ProductName->Caption = ProductName; 
AboutBox->Version->Caption = Version; 
AboutBox->Copyright->Caption = Copyright; 
AboutBox->Comments->Caption = Comments; 
AboutBox->Caption = "About " + ProductName; 
Result = (AboutBox->ShowModal () == IDOK); 



// construct the About box 



// if product name's left blank ... 

// ... use application title instead 

// copy product name 

// copy version information 

// copy copyright information 

// copy comments 

// set About-box caption 

// execute and set result 



catch ( . . . ) 

{ 

Result = false; 



// if it fails, set Result to false 



AboutBox->Free ( 
return Result = 



IDOK; 



// dispose of About box 

// compare Result to IDOK and return Boolean value 



Aggiungere alia parte public della classe TAboutDlg nel file header ABOUTDLG.H la 
dichiarazione per il metodo Execute: 

class PACKAGE TAboutDlg : public TComponent 
{ 
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public: 

virtual bool __fastcall Executed; 

}; 

Verifica del componente 



Una volta installato il componente della finestra di dialogo, lo si puo usare come si fa 
con le comuni finestre di dialogo, mettendone uno su una scheda ed eseguendo la 
scheda. Un modo rapido per verificare la finestra di dialogo About e quello di 
aggiungere un pulsante a una scheda che mandi in esecuzione la finestra di dialogo 
quando l'utente fa clic sul pulsante. 

Ad esempio, se si e creato una finestra di dialogo About, la si e trasformata in un 
componente e la si e aggiunta alia Component palette, e possibile collaudarla nel 
seguente modo: 

1 Creare un nuovo progetto. 

2 Collocare un componente About sulla scheda principale. 

3 Inserire un pulsante nella scheda. 

4 Fare doppio clic sul pulsante per scrivere il gestore di evento clic. 

5 Inserire la seguente linea di codice: 

AboutBoxDlgl->Execute ( ) ; 

6 Eseguire l'applicazione. 

Quando appare la scheda principale, fare clic sul pulsante. Apparira la finestra About 
con l'icona predefinita del progetto e il nome Projectl. Scegliere OK per chiudere la 
finestra di dialogo. 

Si puo collaudare ulteriormente il componente impostando le varie proprieta del 
componente About ed eseguendo nuovamente l'applicazione. 
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Estensione dell'IDE 



E possibile estendere e personalizzare 1' IDE con voci di menu, pulsanti della barra 
strumenti, wizard dinamici per la creazione di schede e altro, utilizzando le API di 
Open Tools (spesso abbreviate in API Tools). Le API Tools sono un insieme di piu di 
100 interfacce (classi astratte) che interagiscono con e controllano TIDE , compresi il 
menu principale, le barre strumenti, l'elenco delle azioni principali e delle immagini, 
i buffer dell'editor interno dei sorgenti, le macro e i collegamenti di tastiera, le schede 
e i relativi componenti nell'editor delle schede, il debugger e il processo in fase di 
debug, il completamento del codice, la vista dei messaggi e la lista To-Do. 

Utilizzare le API Tools significa semplicemente scrivere classi che implementano 
alcune interfacce e chiamare i servizi forniti da altre interfacce. II codice delle API 
Tools deve essere compilato e caricato nell'IDE in fase di progettazione come un 
package di progettazione oppure in una DLL. Quindi, scrivere un'estensione delle 
API Tools e piu o meno come scrivere un editor di proprieta o di un componente. 
Prima di affrontare questo capitolo, assicurarsi di avere familiarita con le nozioni di 
base per operare con i package (Capitolo 15, "Uso di package e di componenti") e per 
registrare componenti (Capitolo 52, "Come rendere disponibili i componenti in fase 
di progetto"). Sarebbe anche bene leggere il Capitolo 13, "Supporto del linguaggio 
C++ per la VCL e la CLX", soprattutto la sezione "Eredita e interfacce" a pagina 13-2 
per informazioni sulle interfacce in stile Delphi. 

Questo capitolo tratta i seguenti argomenti: 

• Panoramica sugli strumenti API 

• Scrittura di una classe wizard 

• Ottenimento dei servizi delle API Tools 

• Operazioni con file ed editor 

• Creazione di schede e di progetti 

• Notifica a un wizard di eventi dell'IDE 

• Installazione della DLL di un wizard 
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Panoramica sugli strumenti API 



Tutte le dichiarazioni delle API Tools risiedono in un singolo file header, 
Tools API .hpp; il namespace e Toolsapi. Di solito, per utilizzare le API Tools, si usa il 
package designide: e cioe necessario costruire gli add-in delle API Tools come un 
package di progettazione o come una DLL che utilizza package di esecuzione. Per 
informazioni sui problemi realtivi ai package e alle librerie, vedere "Installazione del 
package del wizard" a pagina 58-7 and "Installazione della DLL di un wizard" a 
pagina 58-23. 

L'interfaccia principale per la scrittura di un'estensione delle API Tools e 
IOTAWizard, ed e per questo che la maggior parte degli add-in dell'IDE sono detti 
wizard. La maggior parte dei wizard di C++Builder e di Delphi sono intercambiabili. 
E possibile scrivere e compilare un wizard in Delphi e utilizzarlo in seguito in 
C++Builder, e viceversa. L'interoperabilita funziona al meglio con lo stesso numero 
di versione, ma e anche possibile scrivere wizard da utilizzare in future versioni di 
entrambi i prodotti. Per ulteriori informazioni sulla compatibility con future versioni, 
vedere "Utilizzo di una DLL senza package di esecuzione" a pagina 58-24. 

Per utilizzare le API Tools, vengono scritte le classi dei wizard che implementano 
una o piu interfacce definite nella unit ToolsAPI. Si ricordi dal Capitolo 13 che 
C++Builder rappresenta un'interfaccia Object Pascal come una classe astratta. Per 
implementare l'interfaccia, e necessario ridefinire le funzioni membro della classe 
astratta e i suoi antenati e implementare la funzione Querylnterface per riconoscere 
l'interfaccia GUID. 

Un wizard utilizza i servizi forniti dalle API Tools. Ogni servizio e costituito da 
un'interfaccia che presenta un insieme di funzioni connesse. L'implementazione 
dell'interfaccia e nascosta aU'intemo dell'IDE. Le API Tools pubblicano solo 
l'interfaccia, che puo essere utilizzata per scrivere i wizard senza occuparsi 
dell'implementazione delle interfacce. I vari servizi permettono l'accesso all'editor 
dei sorgenti, al designer delle schede, al debugger e cosi via. La sezione "Ottenimento 
dei servizi delle API Tools" a pagina 58-8 esamina questo argomento in modo 
approfondito. 

II servizio e le altre interfacce rientrano in due categorie di base. E possibile 
distinguerle grazie al prefisso utilizzato per il nome del tipo: 

• NTA (native tools API) garantisce l'accesso diretto agli oggetti effettivi IDE, come 
l'oggetto TMainMenu dell'IDE. Quando vengono utilizzate queste interfacce, il 
wizard deve usare i package di Borland, il che significa anche che il wizard e 
legato a una versione specifica dell'IDE. II wizard puo risiedere in un package di 
progettazione o in una DLL che utilizza i package di esecuzione. 

• OTA (open tools API) non richiedere package e accede all'IDE solo attraverso le 
interfacce. In teoria, si potrebbe scrivere un wizard in qualsiasi linguaggio che 
supporta le interfacce in stile COM, a condizione che sia possibile operare anche 

con la convenzione di chiamata fastcall di Borland e con i tipi Object Pascal 

come AnsiString. Le interfacce OTA non garantiscono il completo accesso all'IDE, 
ma quasi tutte le funzionalita delle API Tools sono disponibili attraverso le 
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interfacce OTA. Se un wizard utilizza solo le interfacce OTA, e possibile scrivere 
una DLL che non dipenda da una versione specifica dell'IDE. 

Le API Tools hanno due tipi di interfacce: un tipo che deve essere implementato dal 
programmatore e un tipo che viene implementato dall'IDE. La maggior parte delle 
interfacce appartiene a quest'ultima categoria: le interfacce definiscono la capacita 
dell'IDE ma nascondono Y implementazione corrente. I tipi di interfacce che devono 
essere implementate ricadono in tre categorie: wizard, notifier e creator: 

• Come e gia stato menzionato in questa sezione, una classe wizard implementa 
l'interfaccia IOTAWizard e le eventuali interfacce derivate. 

• Un notifier e un altro tipo di interfaccia delle API Tools. LTDE utilizza il notifier 
per richiamare il wizard quando accade qualcosa di interessante. II 
programmatore scrive una classe che implementa l'interfaccia notifier e registra il 
notifier con le API Tools e TIDE esegue una call back all'oggetto notifier quando 
l'utente apre un file, modifica il codice sorgente, modifica una scheda, avvia una 
sessione di debug, e cosi via. I notifier vengono trattati in "Notifica a un wizard di 
eventi dell'IDE" a pagina 58-19. 

• Un creator e un altro tipo di interfaccia che e necessario implementare. Le API 
Tools utilizzano un creator per creare nuove unit, progetti o altri file o per aprire i 
file esistenti. La sezione "Creazione di schede e di progetti" a pagina 58-14 tratta 
questi argomenti in modo piu approfondito. 

Altre importanti interfacce sono i moduli e gli editor. Un'interfaccia di modulo 
rappresenta una unit aperta, che ha uno o piu file. Un'interfaccia di editor 
rappresenta un file aperto. Diversi tipi di interfacce editor consentono l'accesso a 
diversi aspetti dell'IDE: l'editor dei sorgente ai file sorgente, il Form designer ai file 
scheda e le risorse di progetto ai file di risorse. La sezione "Operazioni con file ed 
editor" a pagina 58-13 tratta questi argomenti in modo approfondito. 

Le seguenti sezioni descrivono le fasi per la scrittura di un wizard. Fare riferimento ai 
file della guida in linea per i dettagli completi di ogni interfaccia. 
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Ci sono quattro tipi di wizard, che si differenziano per le interfacce implementate 
dalla classe wizard. La Tabella 58.1 descrive i quattro tipi di wizard. 

Tabella 58.1 I quattro tipi di wizard 
Interfaccia Descrizione 

IOTAFormWizard Di solito crea una nuova unit, scheda o altro file 
IOTAMenu Wizard Viene automaticamente aggiunto al menu della guida 
IOTAProjectWizard Di solito crea una nuova applicazione o un altro progetto 
IOTAWizard Wizard eterogeneo che non rientrano in altre categorie 



I quattro tipi di wizard si differenziano solo per il modo in cui il wizard viene 
richiamato dall'utente: 
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• Un menu wizard viene aggiunto al menu Help dell'IDE. Quando l'utente sceglie la 
voce di menu, TIDE chiama la funzione Execute() del wizard. I wizard normali 
offrono una maggiore flessibilita, percio i menu wizard vengono di solito utilizzati 
solo per prototipi e per eseguire il debug. 

• I wizard di scheda e i wizard di progetto vengono chiamati wizard repository 
perche risiedono nell'Object Repository. L'utente chiama questi wizard dalla 
rinestra di dialogo New Items. L'utente puo anche vedere i wizard nell'Object 
Repository (scegliendo la voce di menu Tools I Repository). L'utente puo 
selezionare la casella di controllo New Form di un wizard di scheda, la quale 
comunica all'IDE di chiamare il wizard di scheda quando l'utente sceglie la voce 
di menu File I New Form. L'utente puo inoltre selezionare la casella di controllo 
Main Form. La casella di controllo dice all'IDE di impiegare il wizard delle schede 
come scheda predefinita per una nuova applicazione. L'utente puo controllare la 
casella di controllo New Project per un wizard di progetto. Quando l'utente 
sceglie File I New Application, l'IDE chiama il wizard di progetto selezionato. 

• II quarto tipo di wizard viene utilizzato in situazioni che non rientrano nelle altre 
categorie. Un normale wizard non fa niente automaticamente o da solo. Al 
contario, e necessario definire il modo in cui il wizard viene richiamato. 

Le API Tools non impongono nessuna restrizione al wizard, come richiedere un 
wizard di progetto per creare un progetto. E possibile scrivere semplicemente un 
wizard di progetto per creare una scheda e un wizard di schede per creare un 
progetto (se e qualcosa che si desidera realmente fare). 

Implementazione delle interfacce wizard 



Ogni classe wizard deve implementare almeno IOTAWizard, che richiede di 
implementare anche i suoi antenati: IOTANotifier e Ilnterface. I wizard delle schede e 
dei progetti devono implementare tutte le loro interfacce antenato, cioe, 
IOTARepositoryWizard, IOTAWizard, IOTANotifier e Ilnterface. 

L'implementazione di Ilnterface deve seguire le normali regole delle interfacce Object 
Pascal, che sono le stesse di quelle delle interfacce COM. Vale a dire, Querylnterface 
esegue conversioni di tipo e AddRefe Release gestiscono il conteggio dei riferimenti. Si 
potrebbe volere utilizzare una classe base comune per semplificare la scrittura del 
wizard e delle classi notifier. 

Ad esempio, Delphi ha la classe TNotifierObject, che implementa IOTANotifier con 
corpi di funzione vuoti. E possibile scrivere una classe simile in C++, come verra 
mostrato in seguito. 

class PACKAGE NotifierObject : public IOTANotifier { 
public : 

__fastcall NotifierObject ( ) : ref_count (0) {} 
virtual __fastcall -NotifierObject)); 
void „fastcall Af terSave ( ) ; 
void __fastcall Bef oreSave ( ) ; 
void __fastcall Destroyed)); 
void __fastcall Modified)); 
protected : 
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// Ilnterface 

virtual HRESULT __stdcall Query Interface (const GUID&, void**); 
virtual ULONG __stdcall AddRef ( ) ; 
virtual ULONG __stdcall Release ( ) ; 
private : 

long ref_count; 

}; 

L'implementazione dell'interfaccia Ilnterface e immediata: 

ULONG __stdcall NotifierObject: :AddRef () 

{ 

return Interlockedlncrement (&ref_count) ; 

} 

ULONG __stdcall NotifierObject: :Release() 

{ 

ULONG result = InterlockedDecrement (&ref_count) ; 
if (ref_count == 0) 

delete this ; 
return result; 

} 

HRESULT __stdcall NotifierObject: : Query Interface (const GUID& lid, void** obj) 

{ 

if (lid == __uuidof (Ilnterface) ) { 
*obj = static_cast<llnterface*>(this) ; 
static_cast <llnterf ace*> ( *obj ) ->AddRef ( ) ; 
return S_OK; 

} 

if (lid == __uuidof (iOTANotifier) ) { 
*obj = static_cast<lOTANotifier*>(this) ; 
static.cast <lOTANotif ier*> (*obj ) ->AddRef ( ) ; 
return S_OK; 

} 

return E_NOINTERFACE; 

} 

Benche i wizard ereditino da IOTANotifier e debbano implementare quindi tutte le 
sue funzioni, di solito TIDE non fa uso di queste funzioni, e pertanto le 
implementazioni possono essere vuote: 



void __fastcall NotifierObject: 

void __fastcall NotifierObject: 

void __fastcall NotifierObject: 

void __fastcall NotifierObject: 



AfterSaveO {} 

BeforeSaveO {} 

Destroyed!) {} 

Modified!) {} 



Per utilizzare NotifierObject come classe base e necessario utilizzare l'eredita multipla. 
La classe wizard deve ereditare da NotifierObject e dalle interfacce wizard che devono 
essere implementate, come IOTAWizard. Poiche IOTAWizard eredita da IOTANotifier 
e da Ilnterface, nella classe derivata si crea ambiguita: le funzioni come AddRef () sono 
dichiarate in ogni ramo del grafico dell'albero genealogico dell'eredita. Per risolvere 
questo problema, scegliere una classe base come classe base principale e delegare 
tutte le funzioni ambigue a quella classe. Ad esempio, la dichiarazione della classe 
potrebbe apparire come segue: 

class PACKAGE MyWizard : public NotifierObject, public IOTAMenuWizard { 
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typedef Notif ierObject inherited; 
public : 

// IOTAWizard 

virtual AnsiString __fastcall GetlDString ( ) ; 

virtual AnsiString fastcall GetNameO; 

virtual TWizardState __fastcall GetStateO; 

virtual void fastcall Executed; 

// IOTAMenuWizard 
virtual AnsiString __fastcall GetMenuText ( ) ; 

void __fastcall Af terSave ( ) ; 
void __fastcall BeforeSaveO ; 
void __fastcall Destroyed!); 
void __fastcall Modified!); 
protected : 
// Ilnterface 

virtual HRESULT __stdcall Querylnterf ace (const GUID&, void"); 
virtual ULONG __stdcall AddRef ( ) ; 
virtual ULONG __stdcall Released; 

}; 

L'implementazione della classe potrebbe includere quanto segue: 

ULONG __stdcall MyWizard: : AddRef () { return inherited: :AddRef () ; } 
ULONG __stdcall MyWizard: :Release() { return inherited: :Release () ; } 
HRESULT __stdcall MyWizard: : Query Interface (const GUID& lid, void** obj ) 

{ 

if (iid == __uuidof (IOTAMenuWizard) ) { 
*obj = static_cast<IOTAMenuWizard*>(this) ; 
static_cast <lOTAMenuWizard*> (*obj ) ->AddRef ( ) ; 
return S_0K; 

} 

if (iid == __uuidof (IOTAWizard) ) { 
*obj = static_cast<IOTAWizard*>(this) ; 
static.cast <lOTAWizard*> (*obj ) ->AddRef ( ) ; 
return S_0K; 

} 

return inherited: :QueryInterface(iid, obj); 

} 

Poiche AfterSave, BeforeSave, e cosi via, hanno nella classe base corpi di funzione 
vuoti, nella classe derivata e possibile lasciarli come corpi di funzione vuoti ed 
evitare la chiamata non necessaria a inherited:: After Save (). 

Semplificazione dell'implementazione delle interfacce 



Poiche le interfacce Object Pascal sono simili alle interfacce COM, e possibile 
utilizzare wizard COM come aiuto per la scrittura della classe wizard. Tuttavia, 
COM richiedono molto piu lavoro rispetto a quello richiesto dalle semplici interfacce 
Object Pascal. Con un uso giudizioso di classi base e con qualche operazione di taglia 
e incolla, risultera probabilmente piu semplice non utilizzare i wizard COM, ma 
continuare ad utilizzare semplici implementazioni. Ad esempio, e possibile rendere 
piu semplice l'implementazione di Querylnterface definendo una semplice macro: 
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♦define QUERY_INTERFACE (T, iid, obj) \ 

if ((iid) == uuidof (T) ) { \ 

* (obj ) = static_cast<T*>(this) ; \ 

static.cast <T*> ( * (obj ) ) ->AddRef ( ) ; \ 

return S_0K; \ 

} 

Utilizzare questa macro come segue: 

HRESULT __stdcall MyWizard: : Query Interface (const GUID& iid, void* obj) 
{ 

QUERY_INTERFACE ( IOTAMenuWizard, iid, obj); 
QUERY_INTERFACE (IOTAWizard, iid, obj); 
return inherited: :QueryInterface(iid, obj); 

} 

E necessario anche ridefinire tutte le funzioni membro di IOTAWizard e le classi 
derivate che si utilizzano. La maggior parte delle funzioni delle diverse interfacce 
wizard e auto-esplicativa. L'IDE chiama le funzioni del wizard per decidere come 
presentare il wizard aU'utente e come eseguire il wizard quando l'utente lo richiama. 

Una volta terminata la scrittura della classe wizard, il passaggio successivo e 
l'installazione del wizard. 

Installazione del package del wizard 



Come per qualsiasi altro package di progettazione, un package di wizard deve avere 
almeno una funzione Register. (Vedere il Capitolo 52, "Come rendere disponibili i 
componenti in fase di progetto" per i dettagli sulla funzione Register.) Nella funzione 
Register e possibile registrare qualsiasi numero di wizard chiamando 
RegisterPackageWizard e passando un oggetto wizard come argomento unico, come 
verra descritto in seguito: 

namespace Example { 
void __fastcall PACKAGE Register!) 
{ 

RegisterPackageWizard(new MyWizardO ) ; 
RegisterPackageWizard(new MyOtherWizard( ) ) ; 

} 

} 

E possibile registrare anche editor di proprieta, componenti, e cosi via, come parti 
dello stesso package. 

E bene ricordare che un package di progettazione e parte dell'applicazione principale 
di C++Builder, quindi qualsiasi nome di scheda deve essere univoco per 1' intera 
applicazione e per tutti gli altri package di progettazione. Questo e lo svantaggio 
maggiore nell'utilizzo di package: non si possono conoscere i nomi che altri 
programmatori potrebbero attribuire alle loro schede. 

Durante lo sviluppo, installare il package del wizard nel modo in cui si installerebbe 
qualsiasi altro package di progettazione: fare clic sul pulsante Install nel Package 
manager. L'IDE compilera e colleghera il package e cerchera di caricarlo. L'IDE 
mostra una finestra di dialogo che informa se l'operazione e andata a buon fine. 
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Per fare qualcosa di utile, un wizard deve accedere all'IDE: ai suoi editor, alle sue 
finestre, al suo menu e cosi via. Questo e il ruolo delle interfacce di servizio. Le API 
Tools includono molti servizi, come i servizi delle azioni per eseguire le azioni dei 
file, i servizi dell'editor per accedere all'editor del codice sorgente, i servizi del 
debugger per accedere al debugger, e cosi via. La Tabella 58.2 riassume tutte le 
interfacce di servizio. 

Tabella 58.2 Interfacce di servizi Tools API 



Interfaccia 

INTAServices 

IOTAActionServices 

IOTACodeCompletionServices 

IOTADebuggerServices 
IOTAEditorServices 

IOTAKeyBindingServices 

IOTAKeyboardServices 

IOTAKeyboardDiagnostics 

IOTAMessageServices 

IOTAModuleServices 

IOTAPackageServices 

IOTAServices 
IOTAToDoServices 

IOTAToolsFilter 
IOTAWizardServices 



Descrizione 

Consente l'accesso agli oggetti nativi IDE: menu principale, 
elenco delle azioni, lista delle immagini e barre strumenti. 

Esegue le azioni dei file di base: aprire, chiudere, salvare e 
caricare di nuovo un file. 

Consente l'accesso al completamento del codice, permettendo a 
un wizard di installare un manager custom per il 
completamento del codice. 

Consente l'accesso al debugger. 

Consente l'accesso all' editor del codice sorgente e ai suoi buffer 
interni. 

Consente a un wizard di registrare connessioni di tastiera 
custom. 

Consente l'accesso alle macro e alle connessioni di tastiera. 

Attiva/ disattiva il debug delle combinazioni di tasti. 

Consente l'accesso alia visualizzazione dei messaggi. 

Consente l'accesso per l'apertura dei file. 

Richiede i nomi di tutti i package installati e dei loro 
componenti. 

Servizi vari. 

Consente l'accesso alia lista To-do, permettendo a un wizard di 
installare un manager To-Do custom. 

Registra i notificatori di filtro strumenti. 

Registra e annulla la registrazione dei wizard. 



Per utilizzare un'interfaccia di servizio, convertire la variabile BorlandlDEServices nel 
servizio richiesto utilizzando la funzione membro Supports. Ad esempio, 

void set_keystroke_debugging(bool debugging) 

{ 

_di_lOTAKeyboardDi agnostics diag; 
if (BorlandlDEServices->Supports (diag) ) 
diag->KeyTracing = debugging; 



Se il wizard deve utilizzare spesso un servizio specifico, e possibile conservare un 
puntatore sul servizio come un membro dati della classe wizard. Utilizzando il 
modello Delphilnterface (per esempio, _di_IOTAModuleServices), le API Tools 
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gestiscono automaticamente il periodo di esistenza dell'oggetto e non e necessario 
fare niente di particolare nel distruttore del wizard. 

Utilizzo di oggetti nativi dell'IDE 



I wizard hanno completo accesso al menu principale, alle barre degli strumenti, 
all'elenco delle azioni e delle immagini dell'IDE. (si noti che molti menu contestuali 
dell'IDE non sono accessibili dalle API Tools). Questa sezione presenta un esempio 
semplice di come un wizard puo utilizzare questi oggetti nativi dell'IDE per 
interagire con TIDE. 

Utilizzo dell'interfaccia INTAServices 

L'interfaccia INTAServices e il punto di partenza per operare con oggetti nativi 
dell'IDE. Utilizzare questa interfaccia per aggiungere un'immagine alia lista delle 
immagini, un'azione alia lista delle azioni, una voce di menu al menu principale e un 
pulsante a una barra strumenti. E possibile legare l'azione alia voce di menu e al 
pulsante strumento. Quando il wizard viene distrutto, deve eliminare gli oggetti 
creati, ma non deve cancellare l'immagine che ha aggiunto alia lista di immagini. La 
cancellazione di un'immagine creerebbe disordine negli indici di tutte le immagini 
aggiunte dopo quel wizard. 

II wizard utilizza gli oggetti TMainMenu, TActionList, TImageList e TToolBar effettivi 
dell'IDE, ed e quindi possibile scrivere il codice nello stesso modo in cui si 
scriverebbero altre applicazioni. Inoltre cio significa che potrebbe essere molto facile 
bloccare TIDE o anche disattivare funzionalita importanti, come ad esempio 
cancellare il menu File. 

Aggiunta di un'immagine alia lista delle immagini 

Si supponga di volere aggiungere una voce di menu per richiamare il wizard. Si 
supponga inoltre di voler permettere all'utente di aggiungere un pulsante nella barra 
strumenti che richiami il wizard. II primo passo e aggiungere un'immagine alia lista 
delle immagini dell'IDE. L'indice dell'immagine puo essere quindi utilizzato per 
l'azione, che a sua volta, viene utilizzata dalla voce di menu e dal pulsante della barra 
strumenti. Utilizzare l'lmage editor per creare un file di risorse che contenga una 
risorsa bitmap 16 per 16. Aggiungere il seguente codice al costruttore del wizard: 

_di_INTAServices services; 
BorlandIDEServices->Supports (services) ; 

// Add an image to the image list. 

Graphics : :TBitmap* bitmap (new Graphics : :TBitmap ()) ; 

bitmap->LoadFromResourceName (reinterpret_cast<unsigned> (HInstance) , "Bitmapl") ; 
int image = services->AddMasked(bitmap, bitmap->TransparentColor, 

"Tempest Software. intro wizard image"); 

delete bitmap; 

Si noti che il tipo di HInstance e sbagliato e pertanto e necessario convertirlo nel tipo 
richiesto daLoadFromResourcelD. Assicurarsi inoltre di caricare la risorsa tramite il 
nome o tramite 1TD specificato nel file di risorse. Aggiungere il file di risorse al 
package utilizzando la risorsa #pragma. E necessario scegliere un colore che sara 
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interpretato come colore di sfondo per 1'immagine. Se non si desidera un colore di 
sfondo, scegliere un colore che non esiste nella bitmap. 

Aggiunta di un'azione all'elenco di azioni 

L'indice delle immagini e utilizzato per creare un'azione, come viene mostrato in 
seguito. II wizard utilizza gli eventi OnExecute e Onllpdate. Uno scenario comune e 
che un wizard utilizzi l'evento Onllpdate per attivare o disattivare l'azione. 
Assicurarsi che l'evento Onllpdate ritorni velocemente, altrimenti si notera che l'IDE 
diventa lenta dopo avere caricato il wizard. L'evento OnExecute dell'azione e simile 
al metodo Execute del wizard. Se si utilizza una voce di menu per richiamare un 
wizard di scheda o di progetto, si potrebbe anche volere fare chiamare direttamente 
Execute da OnExecute. 



action 


= new TAction 


ID).; 


action- 


->ActionList = 


services->ActionList ; 


action- 


■>Caption 


GetMenuText ( ) ; 


action- 


■>Hint 


"Display a silly dialog box 


action- 


■>lmagelndex = 


image; 


action- 


■>0nUpdate 


action_update; 


action- 


->OnExecute = 


action_execute; 



La voce di menu imposta la sua proprieta Action all'azione appena creata. L'astuzia 
nel creare una voce di menu sta nel sapere dove inserirla. L'esempio che segue cerca 
il menu View e inserisce la nuova voce di menu come prima voce nel menu View. (Di 
solito, contare su una posizione assoluta non e una buona idea): non si sa mai quando 
un altro wizard si potrebbe inserire nel menu. E probabile che le versioni future di 
C++Builder riordineranno il menu. Un metodo migliore e esaminare il menu 
cercando una voce di menu con un nome specifico. II metodo semplificato viene 
mostrato di seguito per chiarezza). 

for (int i = 0; i < services->MainMenu->Items->Count ; ++i) 

{ 

TMenuItem* item = services->MainMenu->Items->Items [i] ; 
if (CompareText (item->Name, "ViewsMenu") == 0) 

{ 

menu_item = new TMenuItem(O) ; 
menu_item->Action = action; 
item->Insert (0, menu_item) ; 

} 

} 

Aggiungendo l'azione all'elenco delle azioni dell'IDE, l'utente puo vedere l'azione 
mentre personalizza le barre strumenti. L'utente puo selezionare l'azione e 
aggiungerla come pulsante a una qualsiasi barra strumenti. Cio puo causare un 
problema quando viene scaricato il wizard: tutti i pulsanti strumento finiscono per 
dirottare i puntatori sull'azione inesistente e sul gestore di evento OnClicK. Per 
evitare violazioni di accesso, il wizard deve trovare tutti i pulsanti strumento che 
fanno riferimento alia sua azione e rimuoverli. 

Cancellazione di pulsanti dalla barra strumenti 

Non esiste una funzione pratica per la rimozione di un pulsante da una barra 
strumenti; e necessario inviare il messaggio CM_CONTROLCHANGE, in cui il 
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primo parametro e il controllo da cambiare e il secondo parametro e zero se si 
desidera rimuovere quel controllo oppure diverso da zero se si desidera aggiungerlo 
alia barra degli strumenti. Dopo avere rimosso i pulsanti dalla barra degli strumenti, 
il distruttore cancella l'azione e la voce di menu. La cancellazione di questi elementi 
provoca automaticamente la loro rimozione dall'ActionList e dal MainMenu 
dell'IDE. 

void fastcall remove_action (TAction* action, TToolBar* toolbar) 

{ 

for (int i = toolbar->ButtonCount ; --i >= 0; ) 

{ 

TToolButton* button = toolbar->Buttons [1] ; 

if (button->Action == action) 

{ 

// Remove "button" from "toolbar". 

toolbar->Perf orm (CM_CONTROLCHANGE, WPARAM (button) , 0); 

delete button; 

} 

} 

} 

_fastcall MyWizard: :~MyWizard( ) 

{ 

_di_INTAServices services; 
BorlandIDEServices->Supports (services) ; 
// Check all the toolbars, and remove any buttons that use 
// this action. 

remove_action (action, services 
remove_action (action, services 
remove_action (action, services 
remove_action (action, services 
remove_action (action, services 
remove_action (action, services 

delete menu_item; 
delete action; 

} 

Come si puo notare da questo semplice esempio, il wizard interagisce con TIDE in 
modo molto flessibile. Tuttavia, questa flessibilita richiede maggiore responsabilita. E 
facile incorrere in puntatori non corretti o compiere altre violazioni di accesso. Nella 
sezione successiva vengono riportati alcuni suggerimenti su come diagnosticare 
questo genere di errori. 

Debug di un wizard 



Quando si scrivono wizard che utilizzano le API tools native, puo succedere di 
scrivere del codice che provoca il blocco dell'IDE. Puo inoltre succedere di scrivere 
un wizard che si installa ma che non si comporta nel modo desiderate Una delle 
sfide maggiori quando si opera con del codice da utilizzare in fase di progettazione e 
rappresentata dalle operazioni di debug. Tuttavia, e un problema che si puo risolvere 
facilmente. Poiche il wizard e installato in C++Builder stesso, e sufficiente solo 



->ToolBar[sCustomToolBar] ) ; 
->ToolBar[sDesktopToolBar] ) ; 
->ToolBar[sStandardToolBar] ) ; 
->ToolBar[sDebugToolBar] ) ; 
->ToolBar[sViewToolBar] ) ; 
->ToolBar[slnternetToolBar] ) ; 
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impostare, mediante il comando di menu Run I Parameters..., l'Host Application del 
package all'eseguibile di C++Builder (bcb.exe). 

Quando si desidera (o si deve) eseguire il debug del package, non lo si deve 
installare. Scegliere invece Run I Run dalla barra dei menu. Cio avvia una nuova 
istanza di C++Builder. Nella nuova istanza, installare il package gia compilato 
scegliendo Components I Install Package... dalla barra dei menu. Nell'istanza 
originaria di C++Builder, si dovrebbero vedere ora i punti blu rilevatori che indicano 
dove e possibile collocare i breakpoint nel codice sorgente del wizard. (Nel caso non 
si vedano, ricontrollare le opzioni del compilatore per assicurarsi di avere attivato il 
debug; assicurarsi di avere caricato il package corretto; ricontrollare i moduli di 
processo per essere assolutamente certi di avere caricato il file .bpl desidera to). 

Con questa procedura non e possibile eseguire il debug nella VCL, nella CLX o nel 
codice RTL, ma si hanno tutte le possibility di eseguire il debug del wizard stesso, il 
che potrebbe essere sufficiente per individuare cosa non funziona. 

Numeri di versione dell'interfaccia 



Se si osservano attentamente le dichiarazioni di alcune interfacce, come 
IOTAMessageServices, si vedra che esse ereditano da altre interfacce con nomi simili, 
come IOTAMessageServices50, che eredita a sua volta da IOTAMessageServices40. 
L'utilizzo di numeri di versione aiuta a isolare il codice da cambiamenti tra le varie 
versioni di C++Builder. 

Le API Tools seguono il principio di base di COM secondo il quale un'interfaccia e il 
suo GUID non cambiano mai. Se una nuova versione aggiunge delle funzioni a 
un'interfaccia, le API Tools dichiarano una nuova interfaccia che eredita da quella 
precedente. II GUID rimane uguale, collegato all'interfaccia precedente invariata. La 
nuova interfaccia ottiene un GUID completamente nuovo. I wizard precedenti che 
utilizzano il GUID precedente continuano a funzionare. 

Le API Tools cambiano anche i nomi dell'interfaccia per provare a salvaguardare la 
compatibilita del codice sorgente. Per vedere come cio funziona, e importante 
distinguere fra i due tipi di interfacce nelle API Tools: quelle implementate da 
Borland e quelle implementate dall'utente. Se TIDE implementa l'interfaccia, il nome 
corrisponde alia versione piu recente dell'interfaccia. La nuova funzionalita non 
influisce sul codice esistente. Alle vecchie interfacce viene aggiunto il numero della 
versione precedente. 

Per un'interfaccia implementata dall'utente, tuttavia, nuove funzioni membro 
nell'interfaccia di base richiedono nuove funzioni nel codice. Quindi, il nome tende a 
corrispondere alia vecchia interfaccia e alia nuova interfaccia viene aggiunto un 
numero di versione alia fine. 

Si considerino ad esempio i servizi dei messaggi. C++Builder 6 ha introdotto una 
nuova funzione: gruppi di messaggi. Quindi, l'interfaccia dei servizi base per i 
messaggi ha richiesto nuove funzioni membro. Queste funzioni sono state dichiarate 
in una nuova classe di interfaccia, che ha mantenuto il nome IOTAMessageServices. La 
vecchia interfaccia per i servizi di messaggi e stata rinominata IOTAMessageServices50 
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(per la versione 5). II GUID del vecchio lOTAMessageSer vices e lo stesso di quello del 
nuovo IOTAMessageServices50 poiche le funzioni membro sono le stesse. 

Si consideri IOTAIDENotifier come esempio di interfaccia implementata dall'utente. 
C++Builder 5 ha aggiunto nuove funzioni in overload: AfterCompile e BeforeCompile. 
Non e stato necessario cambiare il codice esistente utilizzava IOTAIDENotifier, ma il 
nuovo codice che richiedeva la nuova funzionalita doveva essere modificato per 
ridefinire le nuove funzioni ereditate da IOTAIDENotifier 50. La versione 6 non ha 
aggiunto ulteriori funzioni, pertanto la versione corrente da utilizzare e 
IOTAIDENotifier50. 

La regola empirica quando si scrive del nuovo codice e utilizzare la classe piu 
derivata. Ignorare il codice sorgente se si ricompila semplicemente un wizard 
esistente con una nuova versione di C++Builder. 

Operazioni con file ed editor 



Prima di proseguire, e necessario capire come le API Tools operano con i file. 
L'interfaccia principale e IOTAModule. Un modulo rappresenta un insieme di file 
aperti logicamente collegati. Ad esempio, un singolo modulo rappresenta una 
singola unit. II modulo, a sua volta, ha uno o piu editor, e ogni editor rappresenta un 
file, ad esempio i file di implementazione (.cpp), di interfaccia (.h) o di scheda (.dfm o 
.xfm). Le interfacce dell'editor riflettono lo stato interno degli editor dell'IDE, e 
pertanto un wizard puo vedere il codice e le schede modificati che l'utente vede, 
anche se l'utente non ha salvato nessun cambiamento. 

Utilizzo delle interfacce di modulo 



Per ottenere un'interfaccia di modulo, iniziare con i servizi di modulo 
(IOTAModuleServices). E possibile interrogare i servizi di modulo di tutti i moduli 
aperti, cercare un modulo in base a un nome di archivio o di scheda o aprire un file 
per ottenere la sua interfaccia di modulo. 

Ci sono vari tipi di moduli per vari tipi di file, come progetti, risorse e librerie di tipi. 
Convertire un interfaccia di modulo a un genere specifico di interfaccia di modulo 
per sapere se il modulo e di quel tipo. Ad esempio, il seguente e un modo per 
ottenere l'interfaccia corrente di gruppo del progetto: 

// Return the current project group, or if there is no project group. 
_di_IOTAProjectGroup __fastcall CurrentProjectGroupO 

{ 

_di_IOTAModuleServices svc; 
BorlandIDEServices->Supports (svc) ; 

for (int i = 0; i < svc->ModuleCount ; ++i) 

{ 

_di_lOTAModule module = svc->Modules [i] ; 
_di_IOTAProjectGroup group; 
if (module->Supports (group) ) 
return group; 

} 
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return 0; 

} 

Utilizzo delle interfacce degli editor 



Ogni modulo ha almeno un interfaccia di editor. Alcuni moduli hanno piu editor, 
come un file di implementazione (.cpp), un file di interfaccia (.h) e un file di 
descrizione di scheda(.dfm). Tutti gli editor implementano l'interfaccia IOTAEditor ; 
convertono l'editor in un tipo specifico per sapere di che tipo di editor si tratta. Ad 
esempio, per ottenere l'interfaccia dell'editor di scheda per una unit, e possibile fare 
quanto segue: 

// Return the form editor for a module, or if the unit has no form. 
_di_IOTAFormEditor __fastcall GetFormEditor (_di_IOTAModule module) 

{ 

for (int i = 0; i < module->ModuleFileCount; ++i) 
{ 

_di_IOTAEditor editor = module->ModuleFileEditors [i] ; 
_di_IOTAFormEditor formEditor; 
if (editor->Supports (formEditor) ) 
return formEditor; 

} 

return 0; 

} 

Le interfacce degli editor danno accesso al loro stato interno. E possibile esaminare il 
codice sorgente o i componenti che l'utente sta modificando, apportare modifiche al 
codice sorgente, ai componenti o alle proprieta, modificare la selezione nell'editor 
sorgente e dell'editor delle schede ed eseguire quasi tutte le azioni dell'editor che 
possono essere eseguite dall'utente. 

Un wizard puo accedere a tutti i componenti della scheda utilizzando un'interfaccia 
dell'editor della scheda. Ogni componente (tra cui la scheda principale o il modulo 
dati) ha un'interfaccia associata IOTAComponent. Un wizard puo esaminare o 
cambiare la maggior parte delle proprieta dei componente. Se e necessario avere 
controllo assoluto sul componente, e possibile convertire l'interfaccia 
IOTAComponent in INTAComponent. L'interfaccia nativa del componente consente al 
wizard di accedere direttamente al puntatore INTAComponent. Questo potrebbe 
essere importante se fosse necessario leggere o modificare una proprieta di tipo 
classe, come TFont, il che e possibile solo tramite interfacce in stile NTA. 



Creazione di schede e di progetti 



C++Builder dispone gia di molti wizard per schede e progetti, ed e possibile 
scriverne di propri. L'Object Repository permette di creare modelli statici che 
possono essere utilizzati in un progetto, ma un wizard e molto piu potente perche e 
dinamico. II wizard puo interagire con l'utente e creare vari tipi di file a seconda delle 
risposte dell'utente. Questa sezione descrive come scrivere un wizard per scheda o 
per progetto. 
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Di solito un wizard per scheda o per progetto crea uno o piu file nuovi. Tuttavia al 
posto di file reali, sarebbe meglio creare moduli senza nome e non salvati. Quando 
l'utente li salva, TIDE richiede all'utente un nome per il file. Un wizard utilizza un 
oggetto creator per creare tali moduli. 

Una classe creator implementa un'interfaccia creator, la quale eredita da 
IOTACreator. II wizard passa un oggetto creator al metodo CreateModule del servizio 
del modulo e TIDE richiama l'oggetto creator per ottenere i parametri di cui ha 
bisogno per creare il modulo. 

Ad esempio, un wizard per scheda che crea una nuova scheda implementa di solito 
GetExistingO per restituire false e GetUnnamedO per restituire true. Cio crea un 
modulo che non ha nome (in modo che l'utente debba scegliere un nome prima che il 
file possa essere salvato) e non si appoggia ad alcun file esistente (in modo che 
l'utente debba salvare il file anche se non viene apportato nessun cambiamento). 
Altri metodi del creator comunicano all'IDE il tipo di file che viene creato (per 
esempio, progetto, unit o scheda), forniscono il contenuto del file o restituiscono il 
nome della scheda, il nome dell'antenato e altre importanti informazioni. Ulteriori 
callback consentono a un wizard di aggiungere moduli a un progetto appena creato o 
aggiungono componenti a una scheda appena creata. 

Per creare un nuovo file, come viene spesso richiesto in un wizard per scheda o per 
progetto, e di solito necessario fornirne i contenuti. Per fare cio, scrivere una nuova 
classe che implementa l'interfaccia IOTAFile. Se il wizard e in grado di farlo con i 
contenuti predefiniti del file, e possibile restituire un puntatore da qualsiasi 
funzione che restituisce IOTAFile. 

Ad esempio, si supponga che l'azienda per cui si lavora abbia un blocco di commento 
standard che deve apparire all'inizio di ogni file sorgente. Si potrebbe fare cio 
utilizzando un modello statico nell'Object Repository, ma potrebbe essere necessario 
aggiornare manualmente il blocco di commento per riportare l'autore e la data di 
creazione. Invece, e possibile utilizzare un creator per riempire in modo dinamico il 
blocco di commento al momento della creazione del file. 

II primo passo consiste nello scrivere un wizard che crea nuove unit e nuove schede. 
La maggior parte delle funzioni del creator restituiscono zero, stringhe vuote o altri 
valori predefiniti, i quali comunicano alle API Tools di creare una nuova unit o una 
nuova scheda con il comportamento predefinito. Ridefinire GetCreatorType per 
comunicare alle API Tools se devono creare una unit oppure una scheda. Per creare 
una unit, restituire la macro sUnit. Per creare una scheda, restituire sForm. Per 
semplificare il codice, utilizzare una singola classe che accetti come argomento del 
costruttore il tipo creator. Salvare il tipo creator in un membro dati, in modo da 
permettere a GetCreatorType di restituirne il valore. Ridefinire NewImplSource e 
NewIntfSource per restituire i contenuti del file desiderati. 

class PACKAGE Creator : public IOTAModuleCreator { 
public : 

fastcall Creator (const AnsiString creator_type) 

: ref_count (0) , creator_type (creator_type) {} 
virtual __fastcall -Creator!); 
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// iOTAModuleCreator 
virtual AnsiString __fastcall GetAncestorName ( ) ; 

virtual AnsiString fastcall GetlmplFileName ( ) ; 

virtual AnsiString fastcall GetlntfFileName ( ) ; 

virtual AnsiString fastcall GetForrnName ( ) ; 

virtual bool fastcall GetMamFormO ; 

virtual bool __fastcall GetShowFormO ; 
virtual bool __fastcall GetShowSource ( ) ; 
virtual _di_IOTAFile __fastcall NewFormFile( 

const AnsiString Formldent, const AnsiString Ancestorldent); 
virtual _di_IOTAFile __fastcall NewImplSource ( 

const AnsiString Moduleldent, const AnsiString Formldent, 

const AnsiString Ancestorldent); 
virtual _di_IOTAFile __fastcall Newlnt f Source ( 

const AnsiString Moduleldent, const AnsiString Formldent, 

const AnsiString Ancestorldent); 
virtual void __fastcall FormCreated( 

const _di_IOTAFormEditor FormEditor) ; 

// IOTACreator 
virtual AnsiString __fastcall GetCreatorType ( ) ; 
virtual bool __fastcall GetExistingO ; 
virtual AnsiString __fastcall GetFileSystemO ; 
virtual _di_lOTAModule __ fastcall GetOwner (); 
virtual bool __fastcall GetUnnamed ( ) ; 

protected : 

// Ilnterface 

virtual HRESULT __stdcall Query Interface (const GUID&, void**); 
virtual ULONG __stdcall AddRef ( ) ; 
virtual ULONG __stdcall Released; 

private : 

long ref_count; 

const AnsiString creator_type; 

}; 

La maggior parte dei membri di Creator restituiscono zero o stringhe vuote. I metodi 
booleani restituiscono true, tranne GetExisting, che restituisce false. II metodo piu 
interessante e GetOwner, che restituisce un puntatore al modulo del progetto 
corrente, oppure se non esiste alcun progetto. Non esiste un modo semplice per 
scoprire il progetto corrente o il gruppo di progetti corrente. GetOwner deve 
esaminare in sequenza invece tutti i moduli aperti. Se viene trovato un gruppo di 
progetti, deve essere l'unico gruppo di progetti aperto, in modo che GetOwner 
restituisca il suo progetto corrente. Altrimenti, la funzione restituisce il primo 
modulo di progetto che trova, oppure se non e aperto alcun progetto. 

_di_IOTAModule __fastcall Creator: : GetOwner () 

{ 

// Return the current project. 
_di_IOTAProject result = 0; 

_di_lOTAModuleServices svc = interface_cast <lOTAModuleServices> (BorlandlDEServices) ; 

for (int i = 0; i < svc->ModuleCount ; ++i) 

begin 

_di_!OTAModule module = svc->Modules [i] ; 
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_di_IOTAProject project; 

_di_IOTAProjectGroup group; 

if (module->Supports (project) ) { 

// Remember the first project module. 

if (result == 0) 
result = project; 
} else if (module->Supports (group) ) { 

// Found the project group, so return its active project. 

result = group->ActiveProject; 

break ; 

} 

} 

return result; 

} 

II creator restituisce da NewFormSource, per generare un file scheda predefinito. I 
metodi interessanti sono NewImplSource e NewIntfSource, che creano un'istanza di 
IOTAFile che restituisce i contenuti del file. 

La classe File implementa l'interfaccia IOTAFile. Questa interfaccia restituisce -1 
come eta del file (il che significa che il file non esiste) e restituisce i contenuti del file 
come stringa. Per mantenere semplice la classe File, il creator genera la stringa e la 
classe File la trasmette semplicemente. 

class File : public IOTAFile { 
public : 

__fastcall Filefconst AnsiString source); 
virtual fastcall -Filed; 

AnsiString __fastcall GetSource ( ) ; 
System: :TDateTime __fastcall GetAgeO; 
protected : 

// Ilnterface 

virtual HRESULT __stdcall Query Interface (const GUID&, void**); 
virtual ULONG __stdcall AddRef ( ) ; 
virtual ULONG __stdcall Release ( ) ; 
private : 

long ref_count; 
AnsiString source; 

__fastcall File: :File(const AnsiString source) 

: ref_count (0) , source (source) 

{} 

AnsiString __fastcall File: :GetSource ( ) 
return source; 

System: :TDateIime __fastcall File: :GetAge ( ) 
return -1; 

E possibile conservare il testo del contenuto del file in una risorsa per renderne piu 
semplice la modifica, ma per maggiore semplicita, questo esempio scrive 
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direttamente il codice sorgente nel wizard. Supponendo che ci sia una scheda, 
l'esempio seguente genera il codice sorgente. E possibile aggiungere con facilita il 
caso piu semplice di una unit normale. Controllare Formldent esee vuoto, creare una 
unit normale; altrimenti creare una unit di scheda. Lo scheletro di base del codice e lo 
stesso dell'impostazione predefinita dell'IDE (con l'aggiunta iniziale dei commenti, 
naturalmente), ma e possibile modificarlo nel modo desiderate 

_di_IOTAFile __fastcall Creator: :NewImplSource ( 
const AnsiString Moduleldent, 
const AnsiString Formldent, 
const AnsiString Ancestorldent ) 

{ 

const AnsiString form_source = 

/* \ n . 

%m - description\n" 
Copyright © %y Your company, inc.\n" 
Created on %d\n" 
By %u\n" 

*/\ n . 

\n» 

♦include <vcl.h>\n" 
♦pragma hdrstop\n" 
\n" 

♦include \ n %m.h\ n \n" 

// \n" 

♦pragma package (smart_init ) \n" 
♦pragma resource \"*.dfm\"\n" 
T%f nf;\n" 

// \ n . 

__fastcall T%m: :T%m(TComponent* Owner) \n" 
: T%a (Owner) \n" 

{\n" 
}\n" 

// \ n - ; 

return new File (expand (form_source, Moduleldent, Formldent, 
Ancestorldent) ) ; 

} 

Si noti che il codice sorgente contiene stringhe con formato %m e %y. Questi sono 
concettualmente simili a printf o ai controlli Format, ma vengono espansi dalla 
funzione di espansione del wizard. Piu precisamente, %m viene espanso 
nell'identificativo del modulo o della unit, %f nel nome della scheda e %a nel nome 
dell'antenato. Si noti come il nome della schada vengo utilizzato per il nome del tipo 
della scheda con l'aggiunta di una T maiuscola. Alcuni specificatori di formato 
aggiuntivi semplificano la generazione del blocco di commento: %d per la data, %u 
per l'utente e %y per l'anno. (La scrittura della funzione di espansione e 
indipendente dalle API Tools ed e proposto come un esercizio per il lettore.) 

Newlntj 'Source e simile a NewImplSource, ma genera il file dell'interfaccia (.h). 

II passo finale consiste nella creazione di due wizard per scheda: uno utilizza sUnit 
come tipo di creator e l'altro utilizza sForm. Con ulteriore vantaggio per l'utente, e 
possibile utilizzare INTAServices per aggiungere una voce di menu al menu File I 
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New al fine di richiamare ciascun wizard. II gestore di evento OnClick della voce di 
menu puo chiamare la funzione Execute del wizard. 

Alcuni wizard possono avere la necessita di attivare o disattivare le voci di menu, a 
seconda di cio che sta avvenendo nell'IDE. Ad esempio, un wizard che controlla un 
progetto in un sistema di controllo del codice sorgente dovrebbe disattivare la sua 
voce di menu Check In se nell'IDE non e aperto alcun file. E possibile aggiungere 
questa funzione al wizard utilizzando i notificatori, come viene spiegato nella 
sezione successiva. 



Notifica a un wizard di eventi dell'IDE 



Un aspetto importante della scrittura di un wizard con un comportamento corretto 
consiste nel fare in modo che il wizard risponda agli eventi dell'IDE. In particolare, 
qualsiasi wizard che tenga traccia delle interfacce dei moduli deve essere in grado di 
rilevare quando l'utente chiude il modulo, in modo che il wizard possa rilasciare 
l'interfaccia. Per fare cio, il wizard necessita di un notificatore, il che significa che e 
necessario scrivere una classe notifier. 

Tutte le classi notifier implementano una o piu interfacce notifier. Le interfacce 
notifier definiscono i metodi delle callback; il wizard registra un oggetto notifier con 
le API Tools e TIDE richiama il notificatore quando accade qualcosa di importante. 

Ogni interfaccia notifier eredita da IOTANotifier, benche non tutti i suoi metodi 
vengano utilizzati per un particolare notificatore. LaTabella 58.3 elenca tutte le 
interfacce notifier e fornisce una breve descrizione per ognuna di esse. 

Tabella 58.3 Le interfacce notifier 
Interfaccia Descrizione 

IOTANotifier 
IOTABreakpointNotifier 
IOTADebuggerNotifier 



IOTAEditLineNotifier 

IOTAEditorNotifier 

IOTAFormNotifier 

IOTAIDENotifier 

IOTAMessageNotifier 

IOTAModuleNotifier 

IOTAProcessModNotifier 

IOTAProcessNotifier 

IOTAThreadNotifier 

IOTAToolsFilterNotifier 



Classe base astrattaper tutti i notificatori 

Per innescare o sostituire un breakpoint nel debugger 

Per eseguire un programma nel debugger o per aggiungere o 
cancellare breakpoint 

Per tracciare gli spostamenti delle righe nell'editor dei sorgenti 

Per modificare o salvare un file sorgente o cambiare i file nell'editor 

Per salvare una scheda oppure modificare la scheda o qualsiasi suo 
componente (o modulo dati) 

Per caricare progetti, per installare package e per altri eventi globali 
dell'IDE 

Per aggiungere o rimuovere pagine (gruppi di messaggio) nella vista 
dei messaggi 

Per modificare, salvare o rinominare un modulo 
Per caricare un modulo di processo nel debugger 
Per creare o distruggere thread e processi nel debugger 
Per modificare lo stato di un thread nel debugger 
Per richiamare un filtro strumenti 
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Per vedere come utilizzare i notificatori, si consideri l'esempio precedente. Mediante 
i creator di modulo, l'esempio crea un wizard che aggiunge un commento ad ogni 
file sorgente. II commento include il nome iniziale della unit, ma l'utente salva quasi 
sempre il file con un nome diverse In questo caso, sarebbe bello se il wizard 
aggiornasse il commento in modo da farlo corrispondere al vero nome del file. 

Per fare cio, e necessario un notificatore di modulo. II wizard salva l'interfaccia del 
modulo che CreateModule restituisce e la utilizza per registrare un notificatore di 
modulo. II notificatore di modulo riceve la notifica quando l'utente modifica il file 
oppure lo salva, ma questi eventi non sono importanti per questo wizard, e pertanto 
AfterSave e le relative funzioni hanno corpi vuoti. La funzione importante e 
ModuleRenamed, che 1'IDE chiama quando l'utente salva il file con un nuovo nome. La 
dichiarazione per la classe notifier del modulo e la seguente: 

class ModuleNotifier : public Notif ierObject , public iOTAModuleNotifier 

{ 

typedef NotifierObject inherited; 
public : 

__fastcall ModuleNotifier (const _di_lOTAModule module) ; 
__fastcall -ModuleNotifier () ; 

// IOTAModuleNotifier 
virtual bool __fastcall CheckOverwriteO ; 

virtual void __fastcall ModuleRenamed (const AnsiString NewName); 

// IOTANotifier 

void __fastcall AfterSave ( ) ; 

void __fastcall BeforeSaveO ; 

void __fastcall Destroyed!); 

void fastcall Modified!); 

protected : 

// Ilnterface 

virtual HRESULT __stdcall Query Interface (const GUID&, void**); 
virtual ULONG __stdcall AddRef ( ) ; 
virtual ULONG __stdcall Released; 
private : 

_di_IOTAModule module; 

AnsiString name; // Remember the module's old name, 

int index; // Notifier index. 

}; 

Un modo per scrivere un notificatore consiste nel fare in modo che esso si registri 
automaticamente nel proprio costruttore. II distruttore annulla la registrazione del 
notificatore. Nel caso di un notificatore di modulo, 1'IDE chiama il metodo Destroyed 
quando l'utente chiude il file. In quel caso, il notificatore deve annullare la propria 
registrazione e rilasciare il suo riferimento all'interfaccia del modulo. L'IDE rilascia il 
proprio riferimento al notificatore, il che riporta a zero il contatore dei riferimenti e 
libera l'oggetto. Pertanto, e necessario scrivere il distruttore con molta attenzione: la 
registrazione del notificatore potrebbe gia essere stata annullata. 

__fastcall ModuleNotifier: :ModuleNotifier (const _di_IOTAModule module) 
: index(-l), module (module) 

{ 

// Register this notifier. 

index = module->AddNotifier(this) ; 
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// Remember the module's old name. 

name = ChangeFileExt (ExtractFileName (module->FileName) , ""); 

} 

__fastcall ModuleNotifier: : -ModuleNotifier!) 

{ 

// Unregister the notifier if that hasn't happened already, 
if (index >= 0) 
module->RemoveNotif ier (index) ; 

} 

void __fastcall ModuleNotifier: :Destroyed( ) 

{ 

// The module interface is being destroyed, so clean up the notifier. 

if (index >= 0) 

{ 

// Unregister the notifier. 
module->RemoveNotif ier (index) ; 
index = -1; 

} 

module = 0; 

} 

L'IDE richiama la funzione ModuleRenamed del notificatore quando l'utente rinomina 
il file. La funzione accetta come parametro il nuovo nome, che il wizard utilizza per 
aggiornare il commento nel file. Per editare il buffer del sorgente, il wizard utilizza 
un'interfaccia edit position. II wizard trova la posizione giusta, ricontrolla di avere 
trovato il testo giusto e sostituisce quel testo con il nuovo nome. 

void fastcall ModuleNotifier: : ModuleRenamed (const AnsiString NewName) 

{ 

// Get the module name from the new file name. 

AnsiString ModuleName = ChangeFileExt (ExtractFileName (NewName) , ""); 
for (int i = 0; i < module->GetModuleFileCount ( ) ; ++i) 

{ 

// Update every source editor buffer. 

_di_lOTAEditor editor = module->GetModuleFileEditor(i) ; 

_di_lOTAEditBuffer buffer; 

if (editor->Supports (buffer) ) 

{ 

_di_IOTAEditPosition pos = buf f er->GetEditPosition ( ) ; 
// The module name is on line 2 of the comment. 
// Skip leading white space and copy the old module name, 
// to double check we have the right spot. 
pos->Move(2, 1); 

pos->MoveCursor(mmSkipWhite I mmSkipRight ) ; 

AnsiString check = pos->RipText ( " " , rf IncludeNumericChars I rflncludeAlphaChars) ; 

if (check == name) 

{ 

pos->Delete (check. Length) )) ; // Delete the old name. 
pos->InsertText (ModuleName) ; // Insert the new name, 
name = ModuleName; // Remember the new name. 

} 

} 

} 

} 
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Cosa accade se l'utente inserisce degli altri commenti prima del nome del modulo? In 
questo caso, e necessario utilizzare un notificatore edit line per tenere traccia del 
numero di riga in cui si trova si trova il nome del modulo. Per fare cio, utilizzare le 
interfacce IOTAEditLineNotifier e lOTAEdithineTr acker , descritte nella guida in linea. 

E bene essere prudenti durante la scrittura dei notificatori. E necessario assicurarsi 
che nessun notificatore soprawiva al suo wizard. Ad esempio, se l'utente utilizzasse 
il wizard per creare una nuova unit e quindi scaricasse il wizard, ci sarebbe ancora un 
notificatore collegato alia unit. I risultati sarebbero imprevedibili, ma molto 
probabilmente, TIDE si bloccherebbe. Quindi, il wizard deve tenere traccia di tutti i 
suoi notificatori e deve annullare la registrazione di ogni notificatore prima che il 
wizard venga distrutto. D'altra parte, se l'utente per prima cosa chiudesse il file, il 
notificatore di modulo riceverebbe una notifica Destroyed, il che significa che il 
notificatore deve annullare la propria registrazione e rilasciare tutti i riferimenti al 
modulo. II notificatore si deve rimuovere anche dall'elenco principale dei notificatori 
del wizard. 

Di seguito viene riportata la versione finale della funzione Execute del wizard. Questa 
funzione crea il nuovo modulo, utilizza l'interfaccia del modulo e crea un notificatore 
di modulo, quindi lo salva in un elenco di interfacce (TInterfaceList). 

void __fastcall DocWizard: : Executed 
{ 

_di_IOTAModuleServices svc; 
BorlandIDEServices->Supports (svc) ; 

_di_lOTAModule module = svc->CreateModule (new Creator (creator_type) ) ; 
_di_IOTAModuleNotif ier notifier = new ModuleNotif ier (module) ; 
list->Add(notifier) ; 

} 

II distruttore del wizard itera passa in esame l'elenco delle interfacce e annulla la 
registrazione di ogni notificatore nell'elenco. II permettere semplicemente all'elenco 
delle interfacce di rilasciare le interfacce elencate non e sufficiente poiche anche 1'IDE 
conserva le stesse interfacce. E necessario comunicare all'IDE di rilasciare le 
interfacce notifier per poter liberare gli oggetti notifier. In questo caso, il distruttore 
inganna i notificatori facendo credere loro che i rispettivi moduli siano stati distrutti. 
In una situazione piu complicata, si trarrebbe maggior vantaggio nello scrivere una 
funzione Unregister separata per la classe notifier. 

__fastcall DocWizard: :~DocWizard( ) 

{ 

// Unregister all the notifiers in the list, 
for (int i = list->Count ; — i >= 0; ) 

{ 

_di_IOTANotifier notifier; 

list->Items [i] ->Supports (notifier) ; 

// Pretend the associated object has been destroyed. 

// That convinces the notifier to clean itself up. 

notifier->Destroyed( ) ; 

list->Delete(i) ; 

} 

delete list; 
delete item; 

} 
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II resto del wizard gestisce i dettagli di routine della registrazione del wizard, 
installando voci di menu e cose simili. La sezione successiva propone ulteriori 
dettagli sulla registrazione di un wizard illustrando come eseguire l'operazione con 
una DLL invece che con un package. 

Installazione della DLL di un wizard 



E possibile installare un wizard anche con una DLL. Assicurarsi che il wizard utilizzi 
la RTL dinamica e i package di esecuzione. Aggiungere il package designide 
all'elenco dei package di esecuzione in Project Options. La DLL deve esportare una 
funzione di inizializzazione il cui nome e INITWIZARD0001. Quando 1'IDE carica la 
DLL, cerca il nome di esportazione speciale e chiama quella funzione. Per esportare 
la funzione e possibile utilizzare un file di definizione del modulo oppure utilizzare 

una dichiarazione declspec(dllexport). In questo caso, e necessario anche evitare di 

modificare il nome; dichiarare poi la funzione come extern "C". 

La funzione deve essere di tipo TWizardlnitProc. Essa accetta come uno degli 
argomenti un puntatore a una funzione di registrazione. Essa chiama questa 
funzione per registrare ogni oggetto wizard, nello stesso modo in cui un wizard di 
package chiama Register PackageWizard. La funzione di inizializzazione dovrebbe 
restituire true nel caso l'operazione sia andata a buon fine oppure false in caso 
contrario. II seguente esempio mostra come scrivere la funzione di inizializzazione. 

extern "C" bool __stdcall __declspec (dllexport) INITWIZARD0001 ( 

const _di_IBorlandIDEServices, 
TWi zardRegisterProc RegisterProc, 
TWizardTerminateProcSt) 

{ 

RegisterProc (new MyWizardO ) ; 
RegisterProc (new MyOtherWizardf ) ) ; 
return true ; 

} 

Se si utilizzano package di esecuzione, il primo argomento per la funzione di 
inizializzazione non e importante. (II primo parametro e trattato in "Utilizzo di una 
DLL senza package di esecuzione" a pagina 58-24) L'argomento finale e un 
riferimento a un puntatore di funzione di una procedura di terminazione. E possibile 
utilizzare questa funzione per eseguire una pulizia globale. Di solito, e possibile 
ignorare l'ultimo parametro perche il wizard dovrebbe pulirsi da se nel suo 
distruttore. 

Per installare la DLL, aggiungere un elemento al file di registro con la seguente 
chiave: 

HKEY_CURRENTJJSER\Software\Borland\C++Builder\6.0\Experts 

II nome dell'elemento dovrebbe essere un nome univoco, come la stringa ID del 
wizard. II valore dovrebbe essere il percorso completo per la DLL. Al successio avvio, 
C++Builder controlla il file di registro e carica tutte le DLL elencate sotto la chiave 
Experts. La DLL rimane caricata mentre 1'IDE e in esecuzione. Quando C++Builder 
termina, scarica la DLL. Cio rallenta il debug, che e il motivo per cui durante lo 
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sviluppo e bene preferire i package di progettazione. Quando si e pronti a rilasciare il 
wizard, e possibile trasformare un package di progettazione in una DLL. 

Se C++Builder comunica che la versione del wizard e sbagliata, significa che non e in 
grado di trovare la funzione INITWIZARD0001. Rincontrollare di avere scritto il 
nome correttamente e di averlo esportato senza modifiche. 

II vantaggio principale dell'utilizzo di DLL invece che di package consiste nel fatto 
che si evita il problema della collisione dei nomi. E possibile includere nella DLL 
tutte le schede desiderate o necessarie senza preoccuparsi del fatto che lo stesso nome 
sia utilizzato in altri wizard. Un altro vantaggio delle DLL consiste nel fatto che e 
possibile progettare la DLL in modo che non sia dipendente da una sola versione di 
C++Builder, ma per fare cio, e assolutamente impossibile utilizzare i package di 
esecuzione, come viene spiegato nella sezione succesiva. 

Utilizzo di una DLL senza package di esecuzione 



Non e necessario utilizzare package di esecuzione con una DLL di wizard. II 
vantaggio principale nell'utilizzare i package di esecuzione e che la DLL e piu 
piccola. Poiche il wizard e utile solo quando e caricato nell'IDE, si sa quali sono i 
package di C++Builder disponibili, e pertanto sara necessario distribuire solo una 
piccola DLL. D'altro canto, i package sono specifici per ogni versione. Se si desidera 
distribuire un wizard che funzioni con piu versioni di C++Builder e di Delphi, non si 
devono utilizzare package di esecuzione. 

Poiche la variabile BorlandlDE Services e definita solo nel package designide, e 
impossibile utilizzare questa variabile. Invece, e necessario utilizzare il primo 
parametro passato alia funzione di inizializzazione, che ha lo stesso valore. II wizard 
deve salvarlo e utilizzarlo per accedere a tutti i servizi delle API Tools, ad esempio, 

extern "C" bool __stdcall __declspec (dllexport) INITWIZARD0001 ( 
const _di_IBorlandIDEServices svc, 
TWizardRegisterProc reg, 
TWizardTerminateProci) 

{ 

LocallDEServices = svc; 
reg(new DocWizard(sUnit) ) ; 
reg(new DocWizard(sForm) ) ; 
return true; 

} 

AnsiString __fastcall DocWizard: :GetDesigner ( ) 
{ 

_di_IOTAServices svc; 
LocalIDEServices->Supports (svc) ; 
return svc->GetActiveDesignerType ( ) ; 

} 

La modalita di progettazione delle API Tools assicura che la DLL continuera a 
funzionare per le nuove versioni di C++Builder. Tutte le vecchie interfacce 
conservano i rispettivi GUID e le nuove interfacce otterranno i nuovi GUID. Vedere 
"Numeri di versione dell'interfaccia" a pagina 58-12 per ulteriori informazioni su 
come le API Tools utilizzano le diverse verioni e i GUID. 
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Per essere indipendente dalla versione, il wizard non puo utilizzare nessuna 
interfaccia nativa (NTA). Cio limita quello che il wizard puo fare. La limitazione 
maggiore e che il wizard non puo accedere alia barra dei menu e agli altri oggetti 
dell'IDE. La maggior parte delle interfacce delle API Tools sono interfacce OTA, e 
pertanto e ancora possibile scrivere wizard utili e interessanti, indipendentemente da 
come viene installato il wizard. 
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Appendice 




Normativa ANSI per le 
implementazioni specifiche 

Alcuni aspetti del linguaggio ANSI C standard non sono definiti in modo esplicito. 
Pertanto, ciascun produttore di un compilatore C e libero di definire singolarmente 
questi aspetti. Questa Appendice descrive come sono stati definiti da Borland questi 
aspetti. I numeri delle sezioni fanno riferimento al C ANSI/ISO Standard, reso 
pubblico nel Febbraio 1990. 

E bene ricordare che fra il linguaggio C e il linguaggio C++ esistono delle differenze; 
questa sezione si riferisce solo alia versione C. Per informazioni sulla conformita al 
linguaggio C++, fare riferimento al sito Web della Borland Community all'indirizzo 
http:/ / community.borland.com/cpp. 

2.1.1.3 Come identificare un diagnostics 

Quando il compilatore viene utilizzato con la combinazione corretta di opzioni, tutti i 
messaggi inizianti con le parole Fatal, Error oppure Warning sono diagnostici, nel 
senso indicate) dall'ANSI. Le opzioni necessarie per assicurare tale interpretazione 
sono elencate nella tabella seguente: 

Tabella A.1 Opzioni necessarie per assicurare il rispetto delle norme ANSI 



Opzione Effetto 

-A Abilita solo le parole chiave ANSI. 

-C- Abilita solo le parole chiave ANSI. 

-i32 Identificatori con almeno 32 caratteri significativi. 

-p- Utilizzo delle convenzioni di chiamata C. 

-w- Disattivazione di tutti i messaggi di segnalazione. 

-wbei Attivazione di messaggi di segnalazione sugli inizializzatori non appropriate 

-wbig Attivazione di messaggi di segnalazione sulle costanti troppo grandi. 

-wept Attivazione di messaggi di segnalazione sul confronto di puntatori non portabili. 
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Tabella A.1 Opzioni necessarie per assicurare il rispetto delle norme ANSI 
Opzione Effetto 

-wdcl Attivazione di messaggi di segnalazione su dichiarazioni senza tipo o classe di 

memorizzazione. 

-wdup Attivazione di messaggi di segnalazione su definizioni duplicate di macro non 

identiche. 

-wext Attivazione di messaggi di segnalazione sulle variabili dichiarate sia external sia 

static. 

-wfdt Attivazione di messaggi di segnalazione sulla definizione di funzioni mediante un 

typedef. 

-wrpt Attivazione di messaggi di segnalazione sulla conversione di puntatori non 

portabili. 

-wstu Attivazione di messaggi di segnalazione su strutture non definite 

-wsus Attivazione di messaggi di segnalazione su conversioni di puntatore sospette. 

-wucp Attivazione di messaggi di segnalazione sull'utilizzo contemporaneo di puntatori a 

char con e senza segno. 

-wvrt Attivazione di messaggi di segnalazione sulle funzioni void che restituiscono un 

valore. 

Le altre opzioni non indicate esplicitamente possono essere impostate liberamente. 

2.1.2.2.1 La semantica degli argomenti per main. 

Quando il programma viene eseguito da DOS, argv[Q] punta al nome del programma. 

Le rimanenti stringhe argv puntano a ciascun componente degli argomenti della riga 
comandi DOS. Gli spazi bianchi che separano gli argomenti vengono eliminati e ogni 
sequenza contigua di caratteri diversi dagli spazi bianchi viene ritenuta un solo 
argomento. Le stringhe tra apici vengono gestite correttamente (ossia, come una 
stringa contenente spazi). 

2.1.2.3 Che cosa costituisce una periferica interattiva. 

Una periferica interattiva e qualsiasi periferica che si presenta come la console. 

2.2.1 La sequenza di ordinamento del set di caratteri di esecuzione. 

La sequenza di ordinamento del set di caratteri di esecuzione utilizza il valore dei 
caratteri ASCII. 

2.2.1 Elementi dei set di caratteri sorgente e di esecuzione. 

I set di caratteri del codice sorgente e il set di caratteri di esecuzione sono costituiti 
dal set di caratteri esteso ASCII, supportato dai sistemi IBM PC. Ogni carattere 
diverso da Cfrf+Zpuo apparire in stringhe di testo, nelle costanti di tipo carattere e nei 
commenti. 

2.2.1.2 Caratteri multibyte. 

C++Builder sopporta i caratteri multibyte. 
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2.2.2 Direzione di stampa. 

La stampa procede da sinistra a destra, come avviene normalmente nei PC. 

2.2.4.2 Numero di bit di un carattere del set di caratteri di esecuzione. 

Ogni carattere del set di caratteri di esecuzione e costituito da 8 bit. 

3.1.2 Numero di caratteri iniziali significativi degli identificatori. 

I primi 250 caratteri sono significativi, ma il numero puo venire modificato mediante 
l'opzione (-i) della riga comandi. Gli identificatori, sia interni che esterni, utilizzano 
lo stesso numero di caratteri significativi. (II numero di caratteri significativi degli 
identificatori di C++ e illimitato.) 

3.1.2 Distinzione tra maiuscole e minuscole negli identificatori esterni. 

Di norma, il compilatore forza il linker a distinguere i caratteri maiuscoli da quelli 
minuscoli. Per disattivare tale distinzione, utilizzare l'opzione (-1c-) della riga 
comandi. Nell'IDE e possibile anche utilizzare il comando Project I Options I 
Advanced Linker e spuntare l'opzione Case-insensitive link. 

3.1.2.5 The Rappresentazioni e insiemi di valori dei vari tipi di integer. 
Tabella A.2 Identificazione dei diagnostici in C++ 



Tipo 


Valore minimo 


Valore massimo 


signed char 


-128 


127 


unsigned char 





255 


signed short 


-32,768 


32,767 


unsigned short 





65,535 


signed int 


-2,147,483,648 


-2,147,483,647 


unsigned int 





4,294,967,295 


signed long 


-2,147,483,648 


2,147,483,647 


unsigned long 





4,294,967,295 



Tutti i tipi char utilizzano per la memorizzazione un byte di 8 bit. 
Tutti i tipi short utilizzano 2 byte. 
Tutti i tipi int utilizzano 4 byte. 
Tutti i tipi long utilizzano 4 byte. 

Se viene richiesto l'allineamento (-a), tutti gli oggetti non char di tipo integer saranno 
allineati al byte pari. Se l'allineamento richiesto e -a4, il risultato e un allineamento di 
4 byte. I tipi carattere non vengono mai allineati. 

3.1.2.5 Rappresentazioni e insieme di valori dei tipi di numeri in virgola mobile. 

C++Builder adotta, per tutti i tipi di numero in virgola mobile, i formati IEEE in 
virgola mobile utilizzati dai processori Intel 8086. II tipo float utilizza il formato IEEE 
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real a 32 bit. II tipo double utilizza il formato IEEE real a 64 bit. II tipo long double 
utilizza il formato esteso IEEE real a 80 bit. 

3.1.3.4 Corrispondenza tra set di caratteri sorgente e di esecuzione. 

In un programma in fase di esecuzione, i caratteri contenuti nelle stringhe di testo e 
nelle costanti carattere rimangono immutati. I set di caratteri sorgente e di esecuzione 
sono identici. 

3.1.3.4 Valore di una costante di testo intera, contenente un carattere o una sequenza di 
escape non rappresentati nel set di caratteri di esecuzione fondamentale, o nel set di 
caratteri esteso, per una costante wide character. 

I caratteri wide sono supportati. 

3.1.3.4 Impostazione locale attiva utilizzata per convertire i caratteri multibyte nei 
caratteri wide corrispondenti nel caso delle costanti wide character. 

Le costanti wide character sono riconosciute. 

3.1.3.4 Valore di una costante integer contenente piu di un carattere, o di una costante 
wide character contenente piu di un carattere multibyte. 

Le costanti di tipo carattere contengono uno o due caratteri. Quando i caratteri sono 
due, il primo occupa il bit di ordine inferiore della costante, il secondo quello di 
ordine superiore. 

3.2.1.2 Risultato della conversione di un integer in un integer piu breve con segno, 
oppure risultato della conversione di un integer senza segno in un integer di uguale 
lunghezza con segno, quando il valore non e rappresentabile. 

Le conversioni vengono effettuate semplicemente troncando i bit di ordine superiore. 

I valori con segno vengono memorizzati come valori con complemento a due, per cui 
il numero risultante viene interpretato come un valore di questo tipo. Quando il bit 
di ordine superiore dell'integer piu piccolo e diverso da zero, il valore viene 
interpretato come negative altrimenti come positive 

3.2.1.3 Direzione di troncamento quando un numero integrate viene convertito in un 
numero in virgola mobile che non pub rappresentare esattamente il valore originale. 

II valore integer viene arrotondato al piu prossimo valore rappresentabile. Quindi, 
per esempio, il valore long (2 31 -1) viene convertito nel valore float 2 31 . II rapporto di 
uguaglianza viene scisso secondo le regole dello standard aritmetico IEEE. 

3.2.1.4 Direzione di troncamento o di arrotondamento di un numero in virgola mobile 
convertito in un numero in virgola mobile piu breve. 

II valore integer viene approssimato al piu prossimo valore rappresentabile. II 
rapporto di uguaglianza viene scisso secondo le regole dello standard aritmetico 
IEEE. 
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3.3 Risultato delle operazioni su bit negli integer con segno. 

Gli operatori su bit agiscono sugli integer con segno come se fossero i corrispondenti 
tipi senza segno. II bit di segno viene trattato come un normale bit di dati. II risultato 
viene interpretato come un normale integer con segno in complemento a due. 

3.3.2.3 Esito deH'accesso a un membro di un'unione tramite un membro di tipo diverso. 

L'accesso e consentito, e il membro di tipo diverso accede ai bit memorizzati. Per 
capire come accedere a un membro in virgola mobile tramite un membro di tipo 
diverso, occorre conoscere a fondo come vengono codificati i bit dei valori in virgola 
mobile. Se il membro memorizzato e piu breve del membro utilizzato per accedere al 
valore, i bit in eccesso mantengono i valori che avevano prima che il membro breve 
venisse memorizzato. 

3.3.3.4 Tipo di integer richiesto per accogliere la dimensione massima di una matrice. 

II tipo delle matrici normali e unsigned int, mentre quello delle matrici di grandi 
dimensioni e signed long. 

3.3.4 Esito della conversione di un puntatore in un integer e viceversa. 

Nelle conversioni tra integer e puntatori di dimensioni uguali, i bit non subiscono 
modifiche. Nelle conversioni da un tipo piu lungo a uno piu corto, vengono troncati i 
bit di ordine superiore. Nelle conversioni di un tipo integer piu breve in un tipo 
puntatore piu lungo, l'integer viene prima esteso a un tipo di integer di dimensione 
uguale a quella del tipo puntatore. 

Cosi, gli integer con segno estendono il segno in modo da occupare i nuovi byte. 
Analogamente, i tipi di puntatore di dimensione inferiore, convertiti in tipi integer di 
dimensione maggiore, vengono prima trasformati in un tipo puntatore di 
dimensione uguale a quella del tipo integer. 

3.3.5 Segno del resto delle divisioni tra integer. 

II resto ha segno negativo quando uno dei due operandi e negative Se ambedue gli 
operandi sono positivi, o negativi, il resto ha segno positive 

3.3.6 Tipo di integer richiesto per ospitare la differenza tra due puntatori a elementi di una 
stessa matrice, ptrdiff t. 

II tipo e int con segno. 

3.3.7 Risultato di uno spostamento a destra di un tipo integrate con segno negativo. 

Quando viene spostato a destra, un valore con segno negativo viene esteso con 
segno. 

3.5.1 Spazio effettivo occupato dagli oggetti nei registri mediante lo specificatore di 
classe di memorizzazione register. 

Gli oggetti dichiarati con tipi integer o puntatore a uno, due o quattro byte, possono 
essere messi nei registri. Sono disponibili un minimo due e un massimo di sette 
registri. II numero di registri effettivamente usati dipende da quali registri sono 
necessari per ospitare i valori temporanei nella funzione. 
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3.5.2.1 Interpretazione di un campo di bit semplice come int con segno, oppure come 
campo di bit int senza segno. 

I campi di bit int semplici vengono interpretati come campi di bit signed int. 

3.5.2.1 Ordine di allocazione dei campi di bit all'interno di un int. 

I campi di bit vengono allocati dalla posizione di bit di ordine inferiore a quella di 
ordine superiore. 

3.5.2.1 Riempimento (padding) e allineamento dei membri delle strutture. 

Per impostazione predefinita, nelle strutture non viene usato il riempimento. Se si 
attiva l'opzione word alignment (-a), le strutture vengono riempite in modo da avere 
dimensione pari, mentre i membri non di tipo carattere o array di caratteri vengono 
allineati a un offset multiplo pari. 

3.5.2.1 Superamento del limite di una unita di memorizzazione da parte di un campo di 
bit. 

Se non e richiesto l'allineamento (-a), i campi di bit possono superare i limiti dword, 
ma non vengono mai memorizzati in piu di quattro byte adiacenti. 

3.5.2.2 Scelta del tipo di integer per rappresentare i valori di un tipo enumerazione. 

Tutti gli enumeratori vanno memorizzati come int completi. Se i valori non sono 
contenuti in un int, si memorizzano in un tipo long oppure unsigned long. Questo e 
il comportamento di default, come specificato dall'opzione -b del compilatore. 

II comportamento -b- specifica che le enumerazioni vanno preferibilmente 
memorizzate nel tipo integer piu piccolo in grado di rappresentare i valori. Questo 
include tutti i tipi integrali come, per esempio, signed char, unsigned char, signed 
short, unsigned short, signed int, unsigned int, signed long e unsigned long. 

Per compatibilita con C++, va specificata l'opzione -b-. Infatti, in C++ non e corretto 
memorizzare tutte le enumerazioni come int. 

3.5.3 Accesso a un oggetto di tipo volatile-qualified. 

Ogni riferimento a un oggetto volatile ha accesso all'oggetto. La possibility che 
l'accesso a locazioni di memoria adiacenti consenta anche l'accesso a un oggetto 
dipende dall'impostazione fisica della memoria a livello hardware. Nel caso di 
dispositivi di memoria particolari (per esempio, la memoria video) dipende da come 
il dispositivo e stato progettato. Per la normale memoria del PC, gli oggetti volatili 
vengono utilizzati solo per la memoria cui si puo accedere mediante interrupt 
asincroni, per cui l'accesso a oggetti adiacenti non ha effetto. 

3.5.4 Massimo numero di dichiaratori che possono modificare un tipo aritmetico, di 
struttura o di unione. 

Non esiste un limite specifico al numero di dichiaratori. II numero ammissibile di 
dichiaratori e piuttosto grande, ma si riduce quando i dichiaratori sono annidati 
profondamente in un insieme di blocchi di una funzione. II numero consentito a 
livello di file e almeno 50. 
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3.6.4.2 Massimo numero di valori case in un'istruzione switch. 

Non esiste un limite specifico al numero di istruzioni case in uno switch. Finche c'e 
memoria disponibile per contenere le istruzioni case, il compilatore le accetta. 

3.8.1 Corrispondenza tra il valore di una costante di tipo carattere di un solo carattere in 
un'espressione costante che controlla le inclusioni condizionali e il valore della stessa 
costante nel set di caratteri di esecuzione. Possibility o meno della costante di avere 
valore negativo. 

Tutte le costanti di tipo carattere, anche quelle presenti nelle direttive condizionali, 
utilizzano il medesimo set di caratteri (esecuzione). Le costanti carattere di un solo 
carattere sono negative se il tipo carattere e con segno (default e -K non richiesti). 

3.8.2 Metodo per localizzare i file sorgente includibili. 

Per i nomi di file include racchiusi tra parentesi ad angolo, se le directory include 
vengono immesse dalla riga comandi, i file vengono ricercati in tali directory. La 
ricerca nelle directory avviene nel seguente or dine: 

1 Directory specificate nella riga comandi. 

2 Directory specificate in BCC32.CFG. 

3 Directory attuale se non viene specif icata alcuna directory include. 

3.8.2 Supporto dei nomi racchiusi da doppi apici dei file sorgente incorporabili. 

La ricerca dei nomi di file incorporabili racchiusi da doppi apici avviene nel seguente 
ordine: 

1 La stessa directory del file che contiene l'istruzione #include. 

2 Le directory dei file che includono (#include) quel file. 

3 La directory attuale. 

4 II percorso specif icato dall'opzione /I del compilatore. 

5 I percorsi specificati dalla variabile d'ambiente INCLUDE. 

3.8.2 Relazione tra sequenze di caratteri e nomi dei file sorgente. 

Le barre rovesciate nei nomi dei file include sono interpretate come caratteri distinti, 
non come caratteri di escape. Non viene fatta distinzione tra lettere maiuscole e 
minuscole. 

3.8.8 Definizione di DATE e di TIME quando non sono disponibili. 

Data e ora sono sempre disponibili e utilizzano la data e l'ora di sistema. 

4.1.1 Carattere di separazione decimale. 

II carattere di separazione decimale e il punto (.). 

4.1.5 Tipo dell'operatore sizeof, sizej. 

II tipo di size J e unsigned. 
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4.1.5 Costante puntatore nullo alia quale si espande la macro NULL. 

NULL si espande in uno int, o in uno long. Entrambi sono numeri a 32 bit signed. 

4.2 Messaggi diagnostic! visualizzati e comportamento di terminazione della funzione 
assert. 

II messaggio diagnostico visualizzato e "Assertion failed: espressione, file nomefile, line 
nn", dove espressione e l'espressione che non ha superato la valutazione, nomefile e il 
nome del file sorgente e nn e il numero della riga dove la valutazione e avvenuta. 

Immediatamente dopo il messaggio diagnostico viene chiamato Abort. 

4.3 Aspetti implementativi delle funzioni di verifica dei caratteri e di corrispondenza 
maiuscole/minuscole. 

Vedere la sezione 4.3.1. 

4.3.1 Set di caratteri testati dalle funzioni isalnum, isalpha, iscntrl, islower, isprint e 
isupper. 

I primi 128 caratteri ASCII dell'impostazione locale C predefinita. In alternativa, tutti 
i 256 caratteri. 

4.5.1 Valori restituiti dalle funzioni matematiche in caso di errori di dominio. 

Viene restituito uno IEEE NAN (non un numero). 

4.5.1 Le funzioni matematiche impostano l'espressione integer e/raoal valore della 
macro ERANGE negli errori di underflow?. 

No, solo per altri errori - dominio, singolarita, overflow, perdita totale della 
precisione. 

4.5.6.4 Quando la funzione fmod ha come secondo argomento zero, si verifica un errore 
di domino o viene restituito zero? 

No; fmod(x,0) restituisce 0. 

4.7.1.1 Insieme dei segnali della funzione signal. 

SIGABRT, SIGFPE, SIGILL, SIGINT, SIGSEGV, e SIGTERM. 

4.7.1.1 Semantica di ciascun segnale riconosciuto dalla funzione signal. 

Vedere la descrizione di signal. 

4.7.1.1 Gestione di default e gestione in fase di awio del programma dei segnali 
riconosciuti dalla funzione signal. 

Vedere la descrizione di signal. 
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4.7.1.1 Se I'equivalente di signal(sig, SIG DFL); non viene eseguito prima della chiamata 
di un gestore di segnale, quale blocco del segnale viene messo in atto. 

L'equivalente di signal(sig, SIG_DFL) viene eseguito sempre. 

4.7.1.1 In caso di ricevimento del segnale SIGILL da parte del gestore specificato dalla 
funzione signal, la gestione di default viene resettata oppure no. 

No, non viene resettata. 

4.9.2 Obbligatorieta di far seguire un carattere di nuova riga aH'ultima riga di un flusso di 
testo. 

II carattere di nuova riga non e necessario. 

4.9.2 I caratteri spazio, scritti in un flusso di testo, che precedono immediatamente il 
carattere di nuova riga, compaiono o no quando vengono letti. 

I caratteri compaiono. 

4.9.2 Numero di caratteri null aggiungibili ai dati scritti in stream binari. 

Nessuno 

4.9.3 Posizionamento iniziale all'inizio o alia fine di un file delPindicatore di posizione del 
file di un flusso in modalita append. 

Inizialmente, l'indicatore di posizione del file di uno stream in modalita append 
viene situato all'inizio del file. Viene portato alia fine del file prima di ogni 
operazione di scrittura. 

4.9.3 Troncamento del file associato a un flusso di testo dopo il punto in cui avviene una 
scrittura. 

Una scrittura di byte tronca o non tronca il file a seconda dell'impostazione del 
buffer del file. Conviene stabilire che il comportamento di una scrittura di byte e 
indeterminate 

4.9.3 Caratteristiche del buffer dei file. 

I file possono avere un buffer completo, un buffer di riga, oppure essere privi di 
buffer. Se il file ha il buffer, all'apertura viene creato un buffer predefinito di 512 
byte. 

4.9.3 Esistenza effettiva dei file di lunghezza zero. 

I file di lunghezza zero esistono. 

4.9.3 Possibilita di aprire piu volte uno stesso file. 

E consentito aprire piu volte un file. 
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4.9.4.1 Effetto della funzione remove su un file aperto. 

Non viene controllato specificamente se un file e gia aperto; la responsabilita del 
controllo spetta al programmatore. 

4.9.4.2 Controllo di esistenza del nome, prima di una chiamata di rename. 

Rename restituisce -1 ed errno viene impostato a EEXIST. 

4.9.6.1 Output delle conversioni %p in fprintf. 

L'output e composto da otto cifre esadecimali (XXXXXXXX), riempite con zero, in 
lettere maiuscole (come %081X). 

4.9.6.2 Input delle conversioni %p in fscanf. 

Vedere 4.9.6.1. 

4.9.6.2 Interpretazione del carattere - (hyphen) quando non e ne il primo ne I'ultimo 
carattere dell'elenco di scansione, nelle conversioni %[ in fscanf. 

Vedere la descrizione di scant. 

4.9.9.1 Valore della macro errno, impostato in caso di insuccesso dalle funzioni fgetpos o 
fell. 

EBADF Numero di file errato. 
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4.9.10.4 Messaggi generati da perror. 





Arg list too big 


Math argument 


Attempted to remove current directory 


Memory arena trashed 


Bad address 


Name too long 


Bad file number 


No child processes 


Block device required 


No more files 


Broken pipe 


No space left on device 


Cross-device link 


No such device 


Error 


No such device or address 


Exec format error 


No such file or directory 


Executable file in use 


No such process 


File already exists 


Not a directory 


File too large 


Not enough memory 


Illegal seek 


Not same device 


Inappropriate I/O control operation 


Operation not permitted 


Input/ output error 


Path not found 


Interrupted function call 


Permission denied 


Invalid access code 


Possible deadlock 


Invalid argument 


Read-only file system 


Invalid data 


Resource busy 


Invalid environment 


Resource temporarily unavailable 


Invalid format 


Result too large 


Invalid function number 


Too many links 


Invalid memory block address 


Too many open files 


Is a directory 





4.10.3 Comportamento di calloc, malloc, o realloc quando la dimensione richiesta e zero. 

calloc e malloc ignorano la richiesta e restituiscono 0; realloc libera il blocco. 

4.10.4.1 Comportamento della funzione abort nei confronti dei file aperti e dei file 
temporanei. 

I buffer dei file non vengono scaricati e i file non vengono chiusi. 

4.10.4.3 Stato restituito da exit (EXIT_SUCCESS, oppure EXITFAILURE), se il valore 
dell'argomento e diverso da zero. 

Nessuna segnalazione particolare. Lo stato viene rappresentato da un signed char. 

4.10.4.4 Set dei nomi ambiente e metodo utilizzato per alterare I'elenco di ambiente 
utilizzato da getenv. 

Le stringhe di ambiente sono quelle definite nel sistema operativo mediante il 
comando SET. Volendo modificare le stringhe per la durata del programma attivo, si 
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ricorre a putenv, mentre per modificare permanentemente le stringhe di ambiente 
bisogna utilizzare il comando SET. 

4.10.4.5 II contenuto e i modi di esecuzione delle stringhe mediante le funzioni di sistema. 

La stringa viene interpretata come un comando del sistema operative Vengono 
utilizzati COMSPEC o CMD.EXE e l'argomento stringa viene passato come un 
comando da eseguire. Oltre a tutti i comandi del sistema operativo, possono essere 
eseguiti i file batch e i programmi eseguibili. 

4.11.6.2 Contenuto delle stringhe dei messaggi di errore restituite da strerror. 

Vedere 4.9.10.4. 

4.12.1 Fuso orario locale e Daylight Saving Time (ora legale). 

Definiti in base alia data e all'ora locali del PC. 

4.12.2.1 Base dei tempi. 

E misurata da tick del clock; l'origine e l'istante in cui inizia l'esecuzione del 
programma. 

4.12.3.5 Formati della data e dell'ora. 

C++Builder applica i formati ANSI. 
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Appendice 




Guida di riferimento agli script lato 

server di WebSnap 

Questa appendice spiega il meccanismo con cui lo script viene utilizzato dagli 
adapter WebSnap per generare pagine HTML dinamiche in applicazioni per Web 
server WebSnap. L'appendice e pensata per gli sviluppatori che nei moduli di pagine 
web utilizzano produttori di pagine invece di adapter produttori di pagine. Gli 
adapter produttori di pagine gestiscono la generazione di script automaticamente; i 
normali produttori di pagine necessitano di script aggiunti manualmente nei loro 
modelli di pagina. Le informazioni fornite in questa appendice aiuteranno a scrivere 

10 script nei modelli di pagina. 

Questa appendice potrebbe interessare anche agli utenti di adapter produttori di 
pagine che vogliono capirne meglio l'output. Tuttavia, la manipolazione di script e 
un argomento complesso. Non e necessario capire come generare script per scrivere 
applicazioni di base WebSnap. 

Questa appendice e divisa in tre sezioni. La prima sezione spiega i vari tipi di oggetto 
a cui e possibile accedere nello script. La seconda sezione tratta oggetti globali 
definiti nelle applicazioni WebSnap. La terza sezione contiene esempi JScript che 
mostrano come si pud utilizzare lo script nei modelli delle pagine HTML per estrarre 
informazioni dall'applicazione per Web server. 

Questa appendice vuole essere un riferimento API per le interfacce di script degli 
oggetti. Le descrizioni delle proprieta dell'oggetto includono il nome della proprieta, 

11 tipo di proprieta (come text o Boolean) e specificano se la proprieta puo essere letta 
o scritta. Le descrizioni del metodo iniziano con il nome del metodo e con la sintassi 
chiamante. 
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Tipi di oggetto 



La Tabella B.l elenca i tipi di oggetto generali in grado di gestire script. Questi tipi 
vengono comunemente trovati come proprieta di oggetti come gli oggetti globali. 
Non sono elencati tutti i tipi di oggetto in grado di gestire script, ma solo quei tipi le 
cui istanze possono avere nomi differenti. Ad esempio, esiste un tipo di oggetto 
application. Poiche esiste un solo tipo di oggetto application istanziato in ogni 
applicazione, il tipo application e descritto come oggetto Application nella sezione 
realtiva aglioggetti globali. 

Tabella B.1 Tipi di oggetto di WebSnap 



Tipo di oggetto 

Tipo Adapter (page B-2) 



TipoAdapter Action 
(page B-4) 

Tipo AdapterErrors 
(page B-6) 

Tipo AdapterField (page B-7) 

Tipo AdapterFieldValues 
(page B-ll) 

Tipo AdapterFieldValuesList 
(page B-ll) 

Tipo AdapterHiddenFields 
(page B-12) 

Tipo Adapterlmage 
(page B-12) 

Tipo Module (page B-12) 
Tipo Page (page B-13) 



Descrizione 

Definisce le proprieta e i metodi di un adapter.E possibile 
accedere agli adapter tramite nome come proprieta di un 
Module. 

Definisce le proprieta e i metodi di un'azione di un adapter. Le 
azioni sono indicate da un nome come proprieta di un adapter. 

Definisce la proprieta Errors di un adapter. La proprieta Errors e 
utilizzata per elencare errori che si sono verificati durante 
l'esecuzione di un'azione o la generazione di una pagina. 

Definisce le proprieta e i metodi di un campo di un adapter. I 
campi sono indicati da un nome come proprieta di un Adapter. 

Definisce le proprieta e i metodi della proprieta Values di un 
campo di un adapter. 

Definisce la proprieta e i metodi della proprieta ValuesList di un 
campo di un adapter. 

Definisce la proprieta HiddenFields e HiddenRecordFields di un 
adapter. 

Definisce la proprieta Image dei campi di un adapter e delle 
azioni di un adapter. 

Definisce le proprieta di un Module. E possibile accedere a un 
Module tramite nome come proprieta della variabile Modules. 

Definisce le proprieta di una pagina. E possibile accedere a una 
pagina tramite nome come proprieta dell'oggetto Pages. E 
possibile accedere alia pagina che viene generata utilizzando 
1' oggetto Page. 



Tipo Adapter 



Definisce le proprieta e i metodi di un adapter. E possibile accedere ad adapter 
tramite nome come proprieta di un modulo (per esempio ModuleName Adapter). 

Gli adapter contengono i componenti campo e i componenti azione che 
rappresentano rispettivamente i dati e i comandi. Le istruzioni di uno script lato 
server accedono al valore dei campi dell' adapter e ai parametri delle azioni 
dell'adapter per costruire le schede e le tabelle HTML. 
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Proprieta 

Actions: Enumerator 

Vedere anche: proprieta Fields del tipo Adapter (di seguito), Esempio 8 (page B-23) 

Elenca gli oggetti azione. Utilizzare la proprieta Actions per esaminare in sequenza 
tutte le azioni di un adapter. 

CanModify: Booleano, lettura 

Vedere anche: proprieta CanView del tipo Adapter (sotto) e del tipo Adapter Field 
(pageB-7) 

Indica se l'utente possiede l'autorizzazione per modificare i campi di questo 
adapter. Utilizzare la proprieta CanModify per generare dinamicamente HTML 
che e sensibile ai diritti dell'utente. Ad esempio, una pagina puo includere un 
elemento <input> se CanModify e True oppure <p> se CanModify e False. 

CanView: Booleano, lettura 

Vedere anche: CanModify del tipo Adapter (sopra) e del tipo AdapterField 
(pageB-7) 

Indica se l'utente ha l'autorizzazione per esaminare i campi di questo adapter. 
Utilizzare la proprieta CanModify per generare dinamicamente HTML che e 
sensibile ai diritti dell'utente. 

ClassName_: testo, a sola lettura 

Vedere anche: Name_ (di seguito) 

Identifica il nome della classe del componente adapter. 

Errors: AdapterErrors, lettura 

Vedere anche: Tipo AdapterErrors (page B-6), Esempio 7 (page B-23) 

Elenca gli errori rilevati durante il trattamento di una richiesta HTTP. Gli adapter 
catturano gli errori che si verificano durante la generazione di una pagina HTML o 
l'esecuzione di un'azione dell'adapter. Utilizzare la proprieta Errors per elencare 
gli errori e visualizzare i messaggi di errore su una pagina HTML. 

Fields: Enumerator 

Vedere anche: Actions 

Elenca gli oggetti campo. Utilizzare la proprieta Fields per esaminare in sequenza i 
campi di un adapter. 

HiddenFields: AdapterHiddenFields 

Vedere anche: HiddenRecordFields, tipo AdapterHiddenFields (page B-12), 
Esempio 10 (page B-25), Esempio 22 (page B-37) 

Definisce i campi di input non visualizzati che passano informazioni sullo stato 
dell'adapter. Un esempio di informazioni di stato e una modalita di 
TDataSet Adapter. Edit e Insert sono due possibili valori della modalita. Quando 
TDataSetAdapter e utilizzato per generare una scheda HTML, la proprieta 
HiddenFields definisce un campo non visualizzato per quella modalita. Quando la 



Guida di riferimento agli script lato server di WebSnap B-3 



Tipi di oggetto 



scheda HTML viene inviata, la richiesta HTTP contiene questo valore del campo 
nascosto. Quando viene eseguita un'azione, il valore della modalita viene estratto 
dalla richiesta HTTP. Se la modalitae Insert, nel dataset viene inserita una nuova 
riga. Se la modalita e Edit, viene aggiornata una riga di dataset. 

HiddenRecordFields: AdapterHiddenFields 

Vedere anche: HiddenFields, tipo AdapterHiddenFields (page B-12), Esempio 10 
(page B-25), Esempio 22 (page B-37) 

Definisce i campi di input non visualizzati che passano le informazioni di stato 
necessarie per ogni riga o record nella scheda HTML. Ad esempio, quando 
TDataSetAdapter e utilizzato per generare una scheda HTML, la proprieta 
HiddenRecordFields definira un campo non visualizzato che identifica un valore 
chiave per ogni riga in una tabella HTML. Quando la scheda HTML viene 
inoltrata, la richiesta HTTP conterra questi valori del campo nascosto. Quando 
viene eseguita un'azione che aggiorna piu righe in un dataset, TDataSetAdapter 
utilizza questi valori chiave per individuare le righe da aggiornare. 

Mode: testo, lettura/scrittura 

Vedere anche: Esempio 10 (page B-25) 

Imposta oppure ottiene la modalita dell'adapter. 

Alcuni adapter supportano una modalita. Ad esempio, TDataSetAdapter supporta 
le modalita Edit, Insert, Browse e Query. La modalita influisce sul comportamento 
dell'adapter. Quando TDataSetAdapter e in modalita Edit, l'inoltro di una scheda 
aggiorna una riga in una tabella. Quando TDataSetAdapter e in modalita Insert, 
l'inoltro di una scheda inserisce una riga in una tabella. 

Name j. testo, lettura 

Identifica il nome variabile dell'adapter. 
Records: Enumerator, lettura 

Vedere anche: Esempio 9 (page B-24) 

Elenca i record dell'adapter. Utilizzare la proprieta Records per esaminare in 
sequenza i record dell'adapter per generare una tabella HTML. 

Tipo AdapterAction 



Vedere anche: Tipo Adapter (page B-2),tipo AdapterField (page B-7) 

II tipo AdapterAction definisce le proprieta e i metodi di un'azione dell'adapter. 

Proprieta 

Array: Enumerator 

Vedere anche: Esempio 11 (page B-26) 
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Elenca i comandi di un'azione dell'adapter. Utilizzare la proprieta Array per 
esaminare in sequenza i comandi. Array e Null se l'azione non supporta comandi 
multipli. 

T Adapter GotoP age Action e un esempio di un'azione con comandi multipli. Questa 
azione ha un comando per ogni pagina definita dall'adapter genitore. La proprieta 
Array e utilizzata per generare una serie di collegamenti ipertestuali in modo che 
l'utente possa fare clic su uno di essi per spostarsi a un'altra pagina. 

AsFieldValue: testo, lettura 

Vedere anche: AsHREF, Esempio 10 (page B-25), Esempio 21 (page B-36) 

Fornisce un valore di testo che puo essere inviato in un campo non visualizzato. 

AsFieldValue identifica il nome e i parametri dell'azione. Immettere questo valore 

in un campo nascosto di nome act. Quando la scheda HTML viene inoltrata, il 

dispatcher dell'adapter puo estrarre il valore dalla richiesta HTTP e utilizzarlo per 
individuare e chiamare l'azione dell'adapter. 

AsHREF: testo, lettura 

Vedere anche: AsFieldValue, Esempio 11 (page B-26) 

Fornisce un valore del testo che puo essere utilizzato come valore dell'attributo 
href in un marcatore <a>. 

AsHREF identifica il nome e i parametri dell'azione. Immettere questo valore in un 
marcatore anchor per richiedere di eseguire questa azione. Si noti che un 
marcatore anchor su una scheda HTML non permettera l'inoltro della scheda. Se 
l'azione utilizza valori inviati della scheda, utilizzare un campo di scheda nascosto 
e AsFieldValue per identificare l'azione. 

CanExecute: Booleano, lettura 

Indica se l'utente ha i diritti necessari per eseguire questa azione. 
DisplayLabel: testo, lettura 

Vedere anche: Esempio 21 (page B-36) 

Suggerisce un'etichetta HTML di visualizzazione per questa azione dell'adapter. 
DisplayStyle: stringa, lettura 

Vedere anche: Esempio 21 (page B-36) 

Suggerisce uno stile HTML di visualizzazione per questa azione. 

Lo script lato server puo utilizzare DisplayStyle per determinare come generare il 
codice HTML. Gli adapter nativi possono restituire uno dei seguenti stili di 
visualizzazione: 



Valore 


Significato 




Stile di visualizzazione non definito 


'Button' 


Viene visualizzato come <input type="submit"> 


'Anchor' 


Utilizza <a> 
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Enabled: Booleano, lettura 

Vedere anche: Esempio 21 (page B-36) 

Indica se questa azione dovrebbe essere abilitata sulla pagina HTML. 
Name: stringa, lettura 

Fornisce il nome della variabile di questa azione dell'adapter 
Visible: Booleano, lettura 

Indica se questo campo dell'adapter dovrebbe essere visibile sulla pagina HTML. 

Metodi 

LinfcToPage(PageSuccess, PageFail): Adapter Action, lettura 

Vedere anche: Esempio 10 (page B-25), Esempio 11 (page B-26), Esempio 21 
(page B-36), oggetto Page , tipo AdapterAction (page B-4) 

Utilizzare LinkToPage per specificare le pagine che devono essere visualizzate 
dopo che l'azione e stata eseguita. II primo parametro e il nome della pagina da 
visualizzare se l'azione e stata eseguita con successo. II secondo parametro e il 
nome della pagina da visualizzare se si verificano errori durante l'esecuzione 

Tipo AdapterErrors 

Vedere anche: proprieta Errors del tipo Adapter (page B-2) 

II tipo AdapterErrors definisce le proprieta della proprieta Errors di un adapter. 

Proprieta 

Field: AdapterField, lettura 

Vedere anche: Tipo AdapterField (page B-7) 

Identifica il campo dell'adapter che ha causato un errore. 

Questa proprieta e Null se l'errore non e associato a un particolare campo 
dell'adapter. 

ID: intero, lettura 

Fornisce l'identificativo numerico per un errore. 

Questa proprieta vale zero se non e stato definito un ID. 
Message: testo, lettura 

Vedere anche: Esempio 7 (page B-23) 

Fornisce una descrizione testuale dell'errore. 
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Tipo AdapterField type 



Tipi di oggetto 



Vedere anche: Tipo Adapter (page B-2), Tipo AdapterAction (page B-4) 

II tipo AdapterField definisce le proprieta e i metodi di un campo dell'adapter. 

Proprieta 

CanModify: Booleano, lettura 

Vedere anche: proprieta CanView del tipo AdapterField (di seguito) e del tipo 
Adapter (page B-2) 

Indica se l'utente ha i diritti necessari per modificare il valore di questo campo. 

CanView : Booleano, lettura 

Vedere anche: proprieta CanModify del tipo AdapterField (di seguito) e del tipo 
Adapter (page B-2) 

Indica se l'utente ha i diritti necessari per visualizzare il valore di questo campo. 
DisplayLabel: testo, lettura 

Suggerisce un'etichetta di visualizazione HTML per questo campo dell'adapter. 

DisplayStyle: testo, lettura 

Vedere anche: InputStyle (di seguito), ViewMode (di seguito), Esempio 17 
(pageB-34) 

DisplayStyle suggerisce come visualizzare una rappresentazione a sola lettura del 
valore di un campo. 

Lo script lato server puo utilizzare DisplayStyle per determinare come generare 
HTML. Un campo dell'adapter puo restituire uno dei seguenti stili di 
visualizzazione: 



Valore 


Stile di visualizzazione HTML 




Indefinite 


'Text' 


Utilizza <p>. 


'Image' 


Utilizza <img>. La proprieta Image del campo definisce la proprieta src. 


'List' 


Utilizza <UL>. Elenca la proprieta Values per generare ogni elemento 




<LI>. 



La proprieta ViewMode indica se utilizzare InputStyle o DisplayStyle per generare il 
codice HTML. 

DisplayText: testo, lettura 

Vedere anche: EditText (di seguito), Esempio 9 (page B-24) 

Fornisce il testo da utilizzare quando viene visualizzato il valore del campo 
dell'adapter per la sola lettura. II valore di DisplayText puo includere una 
formattazione numerica. 
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Tipi di oggetto 

DisplayWidth: intero, lettura 

Vedere anche: MaxLength (di seguito) 

Suggerisce una larghezza di visualizzazione, in caratteri, per il valore di un campo 
dell'adapter. 

Se la larghezza di visualizzazione non e definita viene restituito -1. 

EditText: testo, lettura 

Vedere anche: DisplayText (sopra), Esempio 10 (page B-25) 

Fornisce il testo da utilizzare quando viene definito un input HTML per questo 
campo dell'adapter. Di solito il valore di EditText non e formattato. 

Image: Tipo Adapterlmage, lettura 

Vedere anche: Tipo Adapterlmage (page B-12), Esempio 12 (page B-28) 

Fornisce un oggetto che definisce un'immagine per questo campo dell'adapter. 

Viene restituito Null se il campo dell'adapter non fornisce un'immagine. 
InputStyle: testo, lettura 

Vedere anche: DisplayStyle (sopra), ViewMode (sotto), Esempio 17 (page B-34) 

Suggerisce uno stile di input HTML per questo campo. 

Lo script lato server puo utilizzare InputStyle per determinare come generare un 
elemento HTML. Un campo dell'adapter puo restituire uno dei seguenti stili di 
input: 



Valore 


Significato 




Stile di input indefinito. 


'Textlnput' 


Utilizza <input type="text">. 


'Passwordlnput' 


Utilizza <input type="password">. 


'Select' 


Utilizza <select>. Elenca la proprieta ValuesList per generare ogni 
elemento <option>. 


'SelectMultiple' 


Utilizza <select multiplex Elenca la proprieta ValuesList per 
generare ogni elemento <option>. 


'Radio' 


Enumera la proprieta ValuesList per generare uno o piu 
<input type="radio">. 


'CheckBox' 


Enumera la proprieta ValuesList per generare uno o piu 
<input type="checkbox">. 


'TextArea' 


Utilizza <textarea>. 


'File' 


Utilizza <input type="file">. 



La proprieta ViewMode indica se utilizzare InputStyle o DisplayStyle per generare il 
codiceHTML. 

InputName: testo, lettura 

Vedere anche: Esempio 10 (page B-25) 
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Tipi di oggetto 

Fornisce un nome a un elemento di input HTML per modificare questo campo 
dell'adapter. 

Utilizzare InputName quando si genera un elemento HTML <input>, <select> o 
<textarea> per permettere al componente adapter di associare le coppie nome/ 
valore nella richiesta HTTP con i campi dell'adapter. 

MaxLength: intero, lettura 

Vedere anche: DisplayWidth (sopra) 

Indica la lunghezza massima in caratteri che puo essere immessa in questo campo. 

MaxLength e -1 se la lunghezza massima non e definita. 
Name: testo, lettura 

Restituisce il nome della variabile del campo dell'adapter. 

Required: Booleano, lettura 

Indica se viene richiesto un valore per questo campo dell'adapter quando viene 
inoltrata una scheda. 

Value: variant, lettura 

Vedere anche: Values (di seguito), DisplayText (sopra), EditText (sopra) 

Restituisce un valore che puo essere utilizzato nei calcoli. Ad esempio, utilizzare 
Value quando si sommano due valori di campo dell'adapter. 

Values: AdapterFieldValues, lettura 

Vedere anche: ValuesList (di seguito), tipo AdapterFieldValues (page B-10), Value 
(sopra), Esempio 13(page B-28) 

Restituisce un elenco dei valori del campo. La proprieta Values e Null a meno che 
questo campo dell'adapter non supporti piu valori. Un campo con valori multipli 
verrebbe utilizzato, ad esempio, per permettere all'utente di scegliere piu valori in 
un elenco. 

ValuesList: AdapterFieldValuesList, lettura 

Vedere anche: Values (sopra), tipo AdapterFieldValuesList (page B-ll), Esempio 
13 (page B-28) 

Fornisce un elenco di scelte per questo campo dell'adapter. Utilizzare ValuesList 
quando si genera una lista di selezione, un gruppo di caselle di controllo o un 
gruppo di pulsanti di scelta HTML. Ogni elemento in ValuesList ha un valore e 
puo avere un nome. 

Visible: Booleano, lettura 

Indica se questo campo dell'adapter dovrebbe essere visibile sulla pagina HTML. 
ViewMode: testo, lettura 

Vedere anche: DisplayStyle (sopra), InputStyle (sopra), Esempiol7 (page B-34) 

Suggerisce come visualizzare questo valore di campo dell'adapter su una pagina 
HTML. 
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Tipi di oggetto 

Un campo dell'adapter puo restituire uno dei seguenti modi di visualizzazione: 
Valore Modo di visualizzazione 

" Indefinite 

'Input' Genera elementi di scheda HTML modificabili utilizzando <input>, 

<textarea> o <select>. 

'Display' Genera HTML a sola lettura utilizzando <p>, <ul> o <img>. 

La proprieta ViewMode indica se utilizzare InputStyle o DisplayStyle per generare il 
codice HTML. 

Metodo 

IsEqual(\ alore): Booleano 

Vedere anche: Esempio 16 (page B-32) 

Chiamare questa funzione per confrontare una variabile con il valore di un campo 
dell'adapter. 

Tipo AdapterFieldValues 

Vedere anche: proprieta Values del tipo AdapterField (page B-7) 

Fornisce un elenco dei valori del campo. Questa proprieta e supportata dai campi a 
valori multipli dell'adapter. Un campo a valori multipli verrebbe utilizzato, ad 
esempio, per permettere all'utente di selezionare piu valori in una lista di selezione. 

Proprieta 

Records: Enumerator, lettura 

Vedere anche: Esempio 15 (page B-31) 

Elenca i record nell'elenco di valori. 
Value: variant, lettura 

Vedere anche: ValueField (di seguito) 

Restituisce il valore dell'elemento di enumerazione corrente. 

ValueField: AdapterField, lettura 

Vedere anche: Tipo AdapterField (page B-7), Esempio 15 (page B-31) 

Restituisce un campo dell'adapter per l'elemento di enumerazione corrente. 
Utilizzare ValueField, ad esempio, per ottenere DisplayText dell'elemento di 
enumerazione corrente. 

Metodi 

HasValue(V alue): Booleano 

Vedere anche: Esempio 14 (page B-29) 
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Tipi di oggetto 

Indica se un certo valore e nell'elenco di valori del campo. Questo metodo e 
utilizzato per determinare se scegliere un elemento in una lista di selezione HTML 
oppure se selezionare un elemento in un gruppo di caselle di controllo. 

Tipo AdapterFieldValuesList 

Vedere anche: Tipo Adapter (page B-2) 

Fornisce un elenco dei possibili valori per questo campo dell'adapter. 

Utilizzare ValuesList quando si genera una lista di selezione, un gruppo di caselle di 
controllo o un gruppi di pulsanti di opzione HTML. Ogni elemento in ValuesList 
contiene un valore e puo contenere un nome. 

Proprieta 

Image: Adapterlmage, lettura 

Restituisce l'immagine dell'elemento di enumerazione corrente, oppure Null se 
l'elemento non ha un'immagine. 

Records: Enumerator, lettura 

Elenca i record nell'elenco di valori. 
Value: variant, lettura 

Restituisce il valore dell'elemento di enumerazione corrente. 
ValueField: AdapterField, lettura 

Vedere anche: Tipo AdapterField (page B-7), Esempio 15 (page B-31) 

Restituisce un campo dell'adapter per l'elemento di enumerazione corrente. 
Utilizzare ValueField, ad esempio, per ottenere DisplayText per l'elemento di 
enumerazione corrente. 

ValueName: testo, lettura 

Restituisce il nome di testo dell'elemento corrente. ValueName e vuoto se il valore 
non ha un nome. 

Metodi 

ImageOfValueCValue): Adapterlmage 

Ricerca l'immagine associata a questo valore. Restituisce Null se non vi sono 
immagini. 

NameOfValueCV alue): testo 

Ricerca il nome asociato a questo valore. Restituisce una stringa vuota se il valore 
non viene trovato o se il valore non ha un nome. 
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Tipi di oggetto 

Tipo AdapterHiddenFields 



Vedere anche: proprieta HiddenFields e HiddenRecordFields del tipo Adapter 
(pageB-2) 

Fornisce accesso ai nomi e ai valori di campo nascosti che un adapter richiede su 
schede HTML utilizzate per inviare modifiche. 

Proprieta 

Name: testo, lettura 

Restituisce il nome del campo nascosto che viene elencato. 
Value: testo, lettura 

Restituisce il valore della stringa del campo nascosto che viene elencato. 

Metodi 

WriteFie Ws(Response) 

Vedere anche: Esempio 10 (page B-25), Esempio 22 (page B-37) 

Scrive i nomi e i valori del campo nascosto utilizzando <input type="hidden">. 

Chiamare questo metodo per scrivere tutti i campi nascosti HTML su una scheda 
HTML. 

Tipo Adapterlmage 

Vedere anche: Tipo AdapterField (page B-12),tipo AdapterAction (page B-4) 
Rappresenta un'immagine associata a un'azione o a un campo. 

Proprieta 

AsHREF: testo, lettura 

Vedere anche: Esempio 11 (page B-26), Esempio 12 (page B-28) 

Fornisce un'URL che pud essere utilizzata per definire un elemento HTML <img>. 

Tipo di modulo 

Vedere anche: oggetto Modules (page B-16) 

I componenti adapter possono essere contraddistinti da un nome come proprieta di 
un modulo. Utilizzare un modulo anche per elencare gli oggetti in grado di gestire 
script (di solito adapter) di un modulo. 

Proprieta 

Name j. testo, lettura 
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Tipi di oggetto 

Vedere anche: Esempio 20 (page B-36) 

Identifica il nome della variabile del modulo. Questo e il nome utilizzato per 
accedere al modulo come proprieta della variabile Modules. 

ClassNamej. testo, lettura 

Vedere anche: Esempio 20 (page B-36) 

Identifica il nome della classe del modulo. 
Objects: Enumerator 

Vedere anche: Esempio 20 (page B-36) 

Utilizzare Objects per elencare gli oggetti in grado di gestire script (di solito 
adapter) all'interno di un modulo. 

Tipo Page 

Vedere anche: oggetto Page (page B-17), Esempio 20 (page B-36) 
Definisce le proprieta e i metodi di pagine. 

Proprieta 

C<mView. Booleano, lettura 

Indica se l'utente ha i diritti necessari per esaminare questa pagina. 

Una pagina registra i diritti di accesso. CanView confronta i diritti registrati dalla 
pagina con i diritti concessi all'utente. 

DefaultAction: tipo Adapter Action , lettura 

Vedere anche: Esempio 6 (page B-22) 

Identifica l'azione predefinita dell'adapter azione associata a questa pagina. 

Un'azione predefinita e di solito utilizzata quando i parametri devono essere 
passati a una pagina. DefaultActionpub essere Null. 

HREF: testo, lettura 

Vedere anche:: Esempio 5 (page B-22) 

Fornisce un'URL che puo essere utilizzata per generare un collegamento 
ipertestuale con questa pagina utilizzando il marcatore <a>. 

LoginRequired: Booleano, lettura 

Indica se l'utente deve eseguireil login prima di accedere a questa pagina. 

Una pagina registra un flag LoginRequired. Se e True all'utente non e consentito 
accedere a questa pagina a meno che non effettui il login. 

Name: testo, lettura 

Vedere anche: Esempio 5 (page B-22) 
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Oggetti globali 

Fornisce il nome della pagina registrata. 

Se la pagina e pubblicata, PageDispatcher genera la pagina nel caso in cui il nome 
della pagina e un suffisso dell'informazione di percorso della richiesta HTTP. 

Published: Booleano, lettura 

Vedere anche: Esempio 5 (page B-22) 

Indica se l'utente puo accedere a questa pagina specificando il nome della pagina 
come suffisso dell'URL. 

Una pagina registra un flag Published. II dispatcher della pagina indirizzera 
automaticamente una pagina pubblicata. Di solito la proprieta Published viene 
utilizzata durante la generazione di un menu con collegamenti ipertestuale ad 
altre pagine. Le pagine che hanno Published impostato a False non sono elencate nel 
menu. 

Title: testo, lettura 

Vedere anche: Esempio 5 (page B-22), Esempio 18 (page B-35) 

Fornisce il titolo della pagina. 

II titolo viene di solito reso visibile all'utente. 



Oggetti globali 



Gli oggetti globali possono essere referenziati dagli script lato server; negli script e 
possibile utilizzare riferimenti agli oggetti globali che somigliano ai riferimenti agli 
oggetti nel codice sorgente. Ad esempio: 

<%= Application. Title i> 

visualizza il titolo dell'applicazione in una pagina web. 

Gli oggetti globali di script sono elencati di seguito: 



Tabella B.2 Oggetti globali WebSnap 



Oggetto 

Oggetto Application 
(page B-15) 

Oggetto EndUser (page B-16) 
Oggetto Modules (page B-16) 



Oggetto Page (page B-17) 
Oggetto Pages (page B-17) 



Descrizione 

Accede ai campi e alle azioni dell'adapter dell'applicazione, 
come il campo Title. 

Accede ai campi e alle azioni dell'adapter dell'utente, come 
DisplayName dell'utente, l'azione Login e 1'azione Logout. 

Referenzia un modulo di dati o di pagina tramite nome. Le 
variabili Modules possono essere utilizzate anche per elencare i 
moduli dell'applicazione. 

Accede alle proprieta della pagina che viene generata come la 
pagina Title. 

Referenzia una pagina registrata tramite nome. Le variabili 
Pages possono essere utilizzate anche per elencare le pagine 
registrate dell'applicazione. 
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Oggetti globali 



Tabella B.2 Oggetti globali WebSnap 



Oggetto 


Descrizione 


Oggetto Producer (page B-17) 

Oggetto Request (page B-18) 
OggettoResponse (page B-18) 
Oggetto Session (page B-19) 


Scrive ii contenuto HTML che puo includere marcatori 
trasparenti. 

Accede alle proprieta e ai metodi delta richiesta HTTP. 
Scrive dei contenuti HTML nella risposta HTTP. 
Accede alle proprieta delta sessione dell'utente. 


Oggetto Application 



Vedere anche: Tipo Adapter (page B-2) 

L'oggetto Application permette l'accesso alle informazioni sull'applicazione. 

Utilizzare l'oggetto Application per accedere ai campi e alle azioni dell'adapter 
dell'applicazione, come il campo Title. L'oggetto Application e un Adapter, e puo 
quindi essere personalizzato con campi e azioni aggiuntivi. E possibile accedere ai 
campi e alle azioni aggiunti all'adapter dell'applicazione tramite nome come 
proprieta dell'oggetto Application. 

Proprieta 

Designing: Booleano, lettura 

Vedere anche: Esempio 1 (page B-20) 

Indica se l'applicazione web viene progettata nell'IDE. 

Utilizzare la proprieta Designing per generare in modo condizionale del codice 
HTML che deve essere differente in fase di progettazione rispetto a quello della 
fase di esecuzione dell'applicazione web. 

ModulePath: testo, lettura 

Vedere anche: metodo QualifyFileName 

Identifica la posizione dell'applicazione web eseguibile. 

Utilizzare ModulePath per costruire nomi di file che si trovano nella stessa direcoty 
del file eseguibile. 

ModuleFileNatne: testo, lettura 

Vedere anche: metodo QualifyFileName 

Identifica il nome per esteso del file dell'eseguibile. 
Title: testo, lettura 

Vedere anche: Esempio 18 (page B-35) 

Fornisce il titolo dell'applicazione. 

La proprieta Title ha il valore della proprieta T Application Adapter. Di solito questo 
valore viene visualizzato all'inizio delle pagine HTML. 
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Oggetti globali 



Metodi 

QualifyFileName(FileName) : testo 
Vedere anche: Esempio 1 (page B-20) 

Converte un nome di file relativo o un riferimento di directory in un riferimento 
assoltuto. 

QualifyFileName utilizza la posizione della directory dell'eseguibile 
dell'applicazione web per qualificare un nome di file che non e per specificato per 
esteso. II metodo restituisce un nome di file per esteso. Se il parametro FileName e 
per esteso, il nome del file viene restituito invariato. In fase di progettazione, il 
parametro FileName viene qualificato con l'ubicazione della directory del file di 
progetto. 

Oggetto EndUser 

Vedere anche: Adapter type (page B-2) 

Permette l'accesso a informazioni riguardanti l'utente corrente. 

Utilizzare EndUser per accedere ai campi e alle azioni dell'adapter per utente finale, 
come DisplayName dell'utente. E possibile accedere ai campi e alle azioni che sono 
stati aggiunti all'adapter per utente finale tramite nome come proprieta dell'oggetto 

EndUser. 

Proprieta 

DisplayName: testo, lettura 

Vedere anche: Esempio 19 (page B-35) 

Fornisce il nome dell'utente. 
Loggedln: Booleano, lettura 

Vedere anche: Esempio 19 (page B-35) 

Indica se l'utente e connesso. 
LoginFormAction:Tvpo AdapterAction, lettura 

Vedere anche: Esempio 19 (page B-35), tipo AdapterAction(page B-4) 

Fornisce l'azione dell'adapter utilizzataper connettere un utente. 
LogoutAction: tipo AdapterAction , lettura 

Vedere anche: Esempio 19 (page B-35), tipo AdapterAction(page B-4) 

Fornisce l'azione dell'adapter utilizzata per disconnettere un utente. 

Oggetto Modules 

Vedere anche: Esempio 2 (page B-21), Esempio 20 (page B-36) 
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Oggetti globali 



L'oggetto Modules permette l'accesso a tutti i moduli che sono stati istanziati o 
attivati per soddisfare la richiesta HTTP corrente. 

Per referenziare un particolare modulo utilizzare il nome del modulo come proprieta 
della variabile Modules. Per elencare tutti i moduli all'interno dell'applicazione, 
creare un enumeratore utilizzando l'oggetto Modules. 

Oggetto Page 

Vedere anche: Esempio 5 (page B-22), tipo Page (page B-13) 

L'oggetto Page permette l'accesso alle proprieta della pagina che viene generata. 

Vedere il tipo Page per una descrizione delle proprieta e dei metodi dell'oggetto 
Page. 

Oggetto Pages 



Vedere anche: Esempio 5 (page B-22) 

L'oggetto Pages permette l'accesso a tutte le pagine registrate dall'applicazione. 

Per referenziare una pagina particolare utilizzare il nome della pagina come 
proprieta della variabile Pages. Per elencare tutte le pagine all'interno 
dell'applicazione, creare un enumeratore utilizzando l'oggetto Pages. 

Oggetto Producer 



Vedere anche: oggetto Response (page B-18) 

Utilizzare l'oggetto Producer per scrivere del testo contenente marcatori trasparenti. 
I marcatori saranno tradotti dal produttore di pagine e quindi scritti nella risposta 
HTTP. Se il testo non contiene marcatori trasparenti, utilizzare l'oggetto Response 
per migliorare le prestazioni. 

Proprieta 

Content: testo, lettura/scrittura 

Permette l'accesso alia parte dei contenuti della risposta HTTP. 

Utilizzare Content per leggere o scrivere l'intera parte dei contenuti della risposta 
HTTP. L'impostazione a Content permette la traduzione dei marcatori trasparenti. 
Se non si utilizzano marcatori trasparenti, impostare invece Response. Content per 
migliorare le prestazioni. 

Metodi 

Wrife(Value) 

Esegue un'aggiunge alia parte dei contenuti della richiesta HTTP con supporto per 
i marcatori trasparenti. 
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Oggetti globali 

Utilizzare il metodo Write per eseguire un'aggiunta alia parte dei contenuti della 
richiesta HTTP. II metodo Write traduce marcatori trasparenti come: 

Write) 'Translate this: <#MyTag>') 

Se non si utilizzano marcatori trasparenti, utilizzare Response. Write per migliorare 
le prestazioni. 

Oggetto Request 

Fornisce accesso alia richiesta HTTP. 

Utilizza le proprieta dell'oggetto Response per accedere alle informazioni sulla 
richiesta HTTP. 

Proprieta 

Host: testo, lettura 

Riporta il valore dello header Host della richiesta HTTP. 

Host e uguale alia proprieta Host di TWebRequest. 
Pathlnfo: testo, lettura 

Contiene la parte Pathlnfo dell'URL. 

Pathlnfo e uguale alia proprieta InternalPathlnfo di TWebRequest. 

ScriptName: testo, lettura 

Contiene la parte del nome dello script dell'URL, che specifica il nome di 
un'applicazione per Web server. 

ScriptName e uguale alia proprieta Internals 'criptName di TWebRequest. 

Oggetto Response 

Vedere anche: oggetto Producer(page B-17) 

Permette l'accesso alia risposta HTTP. Utilizzare l'oggetto Response per scrivere 
nella parte dei contenuti della risposta HTTP. Se si utilizzano marcatori trasparenti, 
utilizzare l'oggetto Producer invece dell'oggetto Response. 

Proprieta 

Content: testo, lettura /scrittura 

Fornisce accesso alia parte dei contenuti della risposta HTTP. 

Utilizzare Content per leggere o scrivere l'intera parte dei contenuti della risposta 
HTTP. 

Metodi 

Wrife(Value) 
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Esempi JScript 



Vedere anche: Esempio 5 (page B-22) 

Aggiunge Value alia parte del contenuto della richiesta HTTP. 

Utilizzare il metodo Write per aggiungere Value al contenuto della richiesta HTTP. 
II metodo Write non traduce i marcatori trasparenti. 

Utilizzare il metodo Write dell'oggetto Producer per scrivere una stringa che 
contiene uno o piu marcatori trasparenti. 

Oggetto Session 

L'oggetto Session permette l'accesso all'ID e ai valori della sessione. 

Un oggetto Session e utilizzato per tenere traccia delle informazioni sull'utente per 
un breve periodo di tempo 

Proprieta 

SessionlD. Value: testo, lettura/scrittura 

Permette l'accesso all'ID della sessione dell'utente corrente. 
VfliMes(Name): variant, lettura 

Permette l'accesso ai valori conservati nella sessione corrente dell'utente. 



Esempi JScript 



I seguenti esempi JScript dimostrano quali sono le proprieta e i metodi utilizzati dello 
scripting lato server. 

Tabella B.3 Esempi JScript di scripting lato server 

Descrizione 



Esempio 

Esempio 1 (page B-20) 



Esempio 2 
Esempio 3 

Esempio 4 
Esempio 5 



(page B-21) 
(page B-21) 

(page B-21) 
(page B-22) 



Esempio 6 (page B-22) 



Esempio 7 
Esempio 8 



(page B-23) 
(page B-23) 



Esempio 9 (page B-24) 



Utilizza il metodo QualifyFilename dell'oggetto Application per 
generare un riferimento di percorso relativo a un'immagine. 

Dichiara una variabile che referenzia un modulo. 

Elenca i moduli nell'applicazione web e visualizza i loro nomi in una 
tabella HTML. 

Dichiara una variabile che referenzia una pagina registrata. 

Enumera le pagine registrate per generare un menu di collegamenti 
ipertestuali alle pagine pubblicate. 

Enumera le pagine registrate per generare un menu di collegamenti 
ipertestuali alle azioni predefinite delle pagine pubblicate. 

Scrive un elenco di errori rilevati da un adapter. 

Enumera tutti gli oggetti azione di un adapter per visualizzare i 
valori delle proprieta dell'oggetto azione in una tabella HTML. 

Enumera i record di un adapter per visualizzare i valori dei campi 
dell'adapter in una tabella HTML. 
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Tabella B.3 Esempi JScript di scripting lato server (continua) 



Esempio 

Esempio 10 (page B-25) 

Esempio 11 (page B-26) 
Esempio 12 (page B-28) 

Esempio 13 (page B-28) 

Esempio 14 (page B-29) 

Esempio 15 (page B-31) 

Esempio 16 (page B-32) 

Esempio 17 (page B-34) 

Esempio 18 (page B-35) 

Esempio 19 (page B-35) 

Esempio 20 (page B-36) 

Esempio 21 (page B-36) 

Esempio 22 (page B-37) 



Descrizione 

Genera una scheda HTML per modificare i campi dell'adapter e 
inoltrare le azioni dell'adapter. 

Mostra le azioni dell'adapter per supportare l'impaginazione. 

Mostra l'immagine di un campo dell'adapter utilizzando il 
marcatore <img> 

Mostra un campo dell'adapter utilizzando i marcatori <select> e 
<option>. 

Mostra un campo dell'adapter come un gruppo di caselle di 
controllo. 

Mostra i valori di un campo dell'adapter utilizzando i marcatori <ul> 
e <li>. 

Mostra un campo dell'adapter come un gruppo di pulsanti di 
opzione. 

Utilizza le proprieta DisplayStyle, InputStyle andViewMode del 
campo dell'adapter per generare HTML. 

Utilizza le proprieta dell'oggetto Application e dell'oggetto Page per 
generare un'intestazione di pagina. 

Utilizza le proprieta dell'oggetto EndUser per mostrare il nome 
dell'utente, il comando di login e il comando di logout. 

Enumera gli oggetti in un modulo in grado di gestire script. 

Utilizza la proprieta DisplayStyle delle azioni dell'adapter per 
generare HTML. 

Generare una tabella HTML per aggiornare piu record di dettaglio. 



Esempio 1 

Vedere anche: Proprieta Designing e QualifyFileName dell'oggetto Application 
(page B-15), proprieta Pathlnfo dell'oggetto Request (page B-18) 

Questo esempio genera un riferimento di percorso relativo a un'immagine. Se lo 
script e in fase di progettazione referenzia un elenco effettivo; altrimenti referenzia 
un elenco virtuale. 

<% 

function PathlnfoToRelativePath(S) 



{ 



var R = " ; 

var L = S. length 

I = 

while (I < L) 
{ 

if (S.charAt(I) == '/') 

R = R + ' . ./' 
I++ 



return R 
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function Qualify Image (S) 
{ 

if (Application. Designing) 

return Application. QualifyFileName (".. \\ images \\ " + S); // relative directory 
else 

return PathlnfoToRelativePath (Request . Pathlnfo) + '../images/' + S; // virtual 

directory 
} 

%> 

Esempio 2 



Vedere anche: oggetto Modules (page B-16) 

Questo esempio dichiara una variabile che referenzia WebModulel: 

<% var M = Modules .WebModulel %> 

Esempio 3 



Vedere anche: oggetto Modules (page B-16) 

L'esempio 3 enumera i moduli istanziati e ne mostra in una tabella il nome della 
variabile e il nome della classe : 

•ctable border=l> 

<tr><th>Name</thxth>ClassName</thx/tr> 
<% 

var e = new Enumerator (Modules) 
for (; !e.atEnd(); e.moveNext ( ) ) 

{ 

%> 

<trxtdx%=e. item( ) .Name_%></tdxtdx%=e. item( ) ClassName._%x/tdx/tr> 

<% 

} 

%> 

</table> 

Esempio 4 



Vedere anche: oggetto Pages (page B-17), proprieta Title dell'oggetto Page 
(pageB-17) 

Questo esempio dichiara una variabile che referenzia una pagina di nome Home. 
Mostra anche il titolo di Home. 

<% var P = Pages. Home %> 
<p><%= P. Title %></p> 
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Esempio 5 



Vedere anche: oggetto Pages (page B-17), proprieta Published e HREFdell'oggetto 
Page (page B-17), metodo Write dell'oggetto Response (page B-18) 

Questo esempio enumera le pagine registrate e crea un menu visualizzando 
collegamenti ipertestuali a tutte le pagine pubblicate. 

<table> 

<td> 

<% e = new Enumerator (Pages) 
s = " 
c = 

for (; !e.atEnd(); e.moveNext ( ) ) 
{ 

if (e.itemO .Published) 
{ 

if (c>0) s += ' I ' 

if (Page. Name != e. item () .Name) 

s += '<a href=" + e.itemO .HREF + '">' + e.itemO .Title + '</a>' 
else 

s += e.itemO .Title 

C + + 

} 

} 

if (ol) Response. Write(s) 

%> 

</td> 
</table> 

Esempio 6 



Vedere anche: proprieta DefaultAction del tipo DefaultAction(page B-13) 

Questo esempio enumera le pagine registrate e crea un menu che mostra 
collegamenti ipertestuali alle azioni predefinite. 

<table> 
<td> 

<% e = new Enumerator (Pages) 
s = " 
c = 

for (; !e.atEnd(); e.moveNext () ) 
{ 

if (e.itemO .Published) 
{ 

if (c>0) s += ' I ' 

if (Page. Name != e.itemO .Name) 

if (e.itemO .DefaultAction != null) 
s += '<a href="'+e.item() .DefaultAction. AsHREF+'"> +e.item() .Title+'</a>' 

else 

s += '<a href="' + e.itemO. HREF + '">' + e.itemO .Title + '</&>' 

else 
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s += e.itemf) .Title 

C + + 

} 

} 

if (ol) Response. Write(s) 

%> 

</td> 
</table> 

Esempio 7 



Vedere anche: proprieta Errors del tipo Adapter (page B-2), tipo AdapterErrors 
(page B-6), oggetto Modules (page B-16), metodo Write dell'oggetto Response 
(pageB-18) 

Questo esempio scrive un elenco di errori rilevati da un adapter. 

<% { 

var e = new Enumerator (Modules. CountryTable. Adapter. Errors) 
for (; !e.atEnd(); e.moveNext ( ) ) 

{ 

Response. Write("<li>" + e.itemO .Message) 

} 

e.moveFirst () 

} %> 

Esempio 8 



Vedere anche: proprieta Actions del tipo Adapter (page B-2), tipo AdapterAction 
(page B-4) 

Questo esempio enumera tutte le azioni di un adapter e mostra in una tabella i valori 
delle proprieta delle azioni. 

<% II Display some properties of an action in a table, 
function DumpAction (A) 

{ 

%> 

<table border="l"> 

<trxth C0LSPAN=2x%=A.Name%x/th> 

<trxth>AsFieldValue:</thxtd><%= A. AsFieldValue %x/td> 
<trxth>AsHREF:</thxtdx%= A.AsHREF %x/span> 
<trxth>DisplayLabel:</thxtdx%= A.DisplayLabel %x/td> 
<trxth>Enabled:</thxtdxl= A. Enabled %x/td> 

<trxth>CanExecute:</thxtdxspan class = "value"x%= A.CanExecute %x/td> 
</table> 

<% 

} 

%> 

<% // Call the DumpAction function for every action in an adapter, 
function DumpActions (A) 

{ 
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var e = new Enumerator (A) 

for (; !e.atEnd(); e.moveNext ( ) ) 

{ 

DumpAction(e.item() ) 

} 




<% 

// Display properties of actions in the adapter named Adapterl. 
DumpActions (Adapterl. Actions) %> 

Esempio 9 



Vedere anche: proprieta Records del tipo Adapter (page B-2), proprieta DisplayText 
del tipo AdapterField (page B-7) 

Questo esempio genera una tabella HTML enumerando i record di un adapter. 

<% 

// Define variables for the adapter and fields. 

vAdapt er=Modules . Count ryTable . Adapt er 
vAdapt er_Name=vAdapt er . Name 
vAdapter_Capital=vAdapter. Capital 
vAdapter_Continent=vAdapter. Continent 
%> 

<% 

II Function to write column text so that all cells have borders, 
function WriteColText (t ) 

{ 

Response.Write((t!="")?t:" ") 

} 

%> 

<table border="l n > 
<tr> 

<th>Narne</th> 

<th>Capital</th> 

<th>Continent</th> 

<% 

// Enumerate all the records in the adapter and write the field values. 

var e = new Enumerator (vAdapter. Records) 
for (; !e.atEnd(); e.moveNext () ) 

{ %> 

<tr> 

<tdxdivxl WriteColText (vAdapter_Name. DisplayText) %x/divx/td> 
<tdxdivx% WriteColText (vAdapter_Capital. DisplayText) %x/divx/td> 
<tdxdivxl WriteColText (vAdapter_Continent .DisplayText) %x/divx/td> 
</tr> 

<% 
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} 

%> 

</table> 

Esempio 10 



Vedere anche: proprieta LinkToPage e lAsFieldValue del tipo AdapterAction 
(page B-4), proprieta InputName e DisplayText del tipo AdapterField (page B-7), 
proprieta HiddenFields e HiddenRecordFields del tipo Adapter (page B-2) 

Questo esempio genera una scheda HTML per modificare i campi dell'adapter e 
inoltra le azioni dell'adapter. 

<% 

// Define some variables for the adapter, fields, and actions. 

vAdapt er=Modules .Count ryTable . Adapt er 
vAdapt er_Name=vAdapt er . Name 
vAdapt er_Capital=vAdapter . Capital 
vAdapter_Continent=vAdapter .Continent 
vAdapt er_Apply=vAdapter. Apply 
vAdapter_Ref reshRow=vAdapter .RefreshRow 

// Put the adapter in Edit mode unless the mode is already set. If the mode is already 
// set this is probably because an adapter action set the mode. For example, an insert 
// row action would put the adapter in Insert mode. 

if (vAdapter.Mode==" " ) 
vAdapter.Mode= ,, Edit n 

%> 

<form name="AdapterForml" method="post"> 
<!-- This hidden field defines the action that is executed when the form is submitted. --> 
<input type="hidden" name="__act"> 



// Write hidden fields defined by the adapter. 

if (vAdapter. HiddenFields != null) 

{ 

vAdapter. HiddenFields .WriteFields (Response) 
} %> 

<% if (vAdapter. HiddenRecordFields != null) 

{ 

vAdapter. HiddenRecordFields. WriteFields (Response) 
} %> 
<table> 
<tr> 
<td> 
<table> 
<tr> 
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<!-- Write input fields to edit the fields of the adapter --> 
<td>Name</td> 

<td xinput type="text" size="24" name=V%=vAdapter_Name.InputName%>" value=" 

<%= vAdapter_Name.EditText %>" ></td> 
</tr> 
<tr> 

<td>Capital</td> 

<td xinput type="text" size="24" name="<l=vAdapter_Capital.InputName%>" 

value="<l= vAdapter_Capital.EditText %>" ></td> 
</tr> 
<tr> 

<td>Continent</td> 

<td xinput type="text" size="24" name="<%=vAdapter_Continent . TnputName%>" 

value="<l= vAdapter_Continent .EditText %>" ></td> 
</tr> 
</table> 

</td> 
</tr> 
<tr> 

<td> 
<table> 

<!-- Write submit buttons to execute actions. Use LinkToPage so this 
page is regenerated after executing an action. --> 

<tr> 

<tdxinput type= 11 submit" value="Apply " 

onclick = "AdapterForml . act.value=' 

<%=vAdapter_Apply. LinkToPage (Page. Name) .AsFieldValue%>'"x/td> 
<tdxinput type="submit" value="Ref resh" 

onclick = "AdapterForml. act.value=' 

<%=vAdapter_Ref reshRow. LinkToPage (Page. Name) .AsFieldValue%>' "> </td> 
</tr> 
</table> 
</td> 
</tr> 
</table> 
</form> 

Esempio 11 



Vedere anche: proprieta Array e AsHREF del tipo AdapterAction (page B-4) 

Questo esempio mostra le azioni dell'adapter per supportare l'impaginazione. Le 
azioni PrevPage, GotoPage e NextPage vengono mostrate come collegamenti 
ipertestuali. L'azione GotoPage ha un array di comandi. I comandi vengono 
enumerati in modo da generare un collegamento ipertestuale per passare ad ogni 
singola pagina. 

// Define variables for the adapter and actions. 
vAdapter = Modules. WebDataModulel. Query Adapter 
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vPrevPage = vAdapter.PrevPage 
vGotoPage = vAdapter.GotoPage 
vNextPage = vAdapter.NextPage 

%> 

<!-- Generate a table that displays hyperlinks between pages. --> 

•ctable cellpadding="5"> 

<tr> 
<td> 
<% 

II Prevpage displays "<<". Use an anchor tag only if the command is enabled. 

if (vPrevPage. Enabled) 
{ %> 

<a href="<?;=vPrevPage.LinkToPage(Page.Name) .AsHREFl>"x«/a> 

<% 

} 

else 

{%> 
<ax«/a> 
<%} %> 
<% 

// GotoPage has a list of commands. Loop through the list. 
// Use an anchor tag only if the command is enabled. 

if (vGotoPage. Array != null) 
{ 

var e = new Enumerator (vGotoPage. Array) 

for (; !e.atEnd(); e.moveNext ( ) ) 

{ 

%> 

<td> 

<% if (vGotoPage. Enabled) 
{ %> 

<a href="<%=vGotoPage.LmkToPage(Page.Name) .AsHREF%>"> 
<%=vGotoPage.DisplayLabel%x/a> 

<% } 

else 
{ %> 

<ax%=vGotoPage.DisplayLabel%x/a> 

<% } 
%> 

</td> 

<% 

} 

} 

%> 

<td> 
<% 

II NextPage displays "»". Use an anchor tag only if the command is enabled. 

if (vNextPage. Enabled) 
{ %> 
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<a href="<?:=vNextPage.LinkToPage(Page.Name) .AsHREF%>"»x/a> 

<% 

} 

else 
{%> 
<a>»</a> 
<%} %> 
</td> 
</table> 

Esempio 12 



Vedere anche: proprieta Image del tipo AdapterField (page B-7) 
L'esempio 12 mostra l'immagine di un campo dell'adapter. 

// Declare variables for the adapter and field. 

vAdapter=Modules .WebDataModule3 .DataSetAdapterl 

vGraphic=vAdapter. Graphic 

%> 

<!-- Display the adapter field as an image. --> 

•cirng src="<l= (vGraphic. Image! =null) ? vGraphic. Image. AsHREF : ''!>" 

a 1 1 = " < % = vGraphi c . Di sp 1 ayText \ > " > 

Esempio 13 



Vedere anche: proprieta Values e ValuesList del tipo AdapterField (page B-7) 

Questo esempio scrive un campo dell'adapter con elementi HTML <select> e 
<option>. 

<% 

// Return an object that defines HTML select options for an adapter field. 
// The returned object has the following elements: 

// 

// text - string containing the <option> elements. 

// count - the number of <option> elements. 

// multiple - string containing the either 'multiple' or ' ' . 

// Use this value as an attribute of the <select> element. 

// 

// Use as follows: 
// obj=SelOptions (f ) 

// Response. Write ( '<select size="' + obj. count + '" name="' + f.lnputName + '" ' + 
// obj .multiple + '>' + obj. text + '</select>') 

function SelOptions (f ) 

{ 

var s=' ' 
var v=' ' 
var n=' ' 
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var c=0 

if (f .ValuesList != null) 

{ 

var e = new Enumerator (f. ValuesList .Records) 

for (; !e.atEnd(); e.moveNext ( ) ) 

{ 

s+= '<option' 

v = f. ValuesList. Value; 

var selected 

if (f. Values == null) 

selected = f.lsEqual(v) 
else 

selected = f. Values. HasValue(v) 
if (selected) 

s += ' selected' 
n = f .ValuesList .ValueName; 
if |n==") 
{ 

n = v 
v = " 

} 

if (v! = ") s += ' value="' + v + "" 
s +='>'+ n + '</option>\r\n' 

C + + 

} 

e.moveFirst () 

} 

r = new Object; 
r.text = s 
r. count = c 

r. multiple = (f. Values == null) ? " : 'multiple' 
return r; 

} 

%> 
<% 

// Generate HTML select options for an adapter field 
function WriteSelectOptions (f ) 

{ 

obj=SelOptions (f ) 

%> 

<select size="<%=obj .count%>" name="<%=f .lnputName%>" <%=ob j .multiple^ > 

<%=obj .text%> 
</select> 

<% 

} 

%> 

Esempio 14 



Vedere anche: proprieta Values e ValuesList del tipo AdapterField (page B-7) 
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Questo esempio scrive un campo dell'adapter come gruppo di elementi 
<input type="checkbox">. 

<% 

// Return an object that defines HTML check boxes for an adapter field. 
// The returned object has the following elements: 

// 

// text - string containing the <input type=checkbox> elements. 
// count - the number of <option> elements. 

// 

// Use as follows to define a check box group with three columns and no additional 
// attributes: 

// obj=CheckBoxGroup(f , 3, ") 
// Response. Writefobj .text) 
// 

function CheckBoxGroup (f ,cols,attr) 

{ 

var s=' ' 
var v=' ' 
var n=' ' 
var c=0; 

var nm=f .InputName 

if (f .ValuesList == null) 

{ 

s+= '<mput type="checkbox"' 

if (f . isEqual (true) ) s+= ' checked' 

s += ' value="true" ' + ' name="' + nm + "" 

if (attr! = ") s+= ' ' + attr 

s += 'x/input>\r\n' 

c = 1 

} 

else 

{ 

s += '<tablextr>' 

var e = new Enumerator (f. ValuesList .Records) 

for (; !e.atEnd(); e.moveNext ( ) ) 

{ 

if (c % cols == 54 C != 0) s += '</trxtr>' 

s+= '<tdxinput type="checkbox'" 

v = f. ValuesList. Value; 

var checked 

if (f. Values == null) 

checked = (f. IsEqual (v) ) 
else 

checked = f. Values. HasValue(v) 
if (checked) 

s+= ' checked' 
n = f. ValuesList. ValueName; 
if (n==") 

n = v 

s += ' value="' + v + "" + ' name="' + nm + "" 

if (attr! = ") s+= ' ' + attr 

s +='>'+ n + '</inputx/td>\r\n' 

C + + 
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} 

e.moveFirst () 

s += '</trx/table>' 

} 

r = new Object; 
r.text = s 
r. count = c 
return r; 

} 

%> 
<% 

// Write an adapter field as a check box group 
function WriteCheckBoxGroup (f, cols, attr) 

{ 

obj=CheckBoxGroup (f , cols, attr) 
Response. Write (obj .text) ; 

} 

%> 

Esempio 15 



Vedere anche: proprieta Values e ValuesList del tipo AdapterField (page B-7), tipo 
AdapterFieldValues (page B-10) 

Questo esempio scrive un campo dell'adapter come elenco di valori a sola lettura 
utilizzando gli elementi <ul> e <li>. 

<% 

// Return an object that defines HTML list values for an adapter field. 
// The returned object has the following elements: 

// 

// text - string containing the <li> elements. 
// count - the number of elements. 

// 

// text will be blank and count will be zero if the adapter field does not 
// support multiple values. 

// 

// Use as follows to define a displays a read only list of this an adapter 

// fields values. 

// obj=ListValues (f ) 

// Response. Write ( '<ul>' + obj. text + '</ul'>') 

// 

function ListValues (f ) 

{ 

var s=' ' 

var v=' ' 

var n=' ' 

var c=0; 

r = new Object; 

if (f. Values != null) 

{ 

var e = new Enumerator (f .Values .Records ) 
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for (; !e.atEnd(); e . moveNext ( ) ) 
{ 

s+= '<li>' 

s += f. Values. ValueField.DisplayText; 
s += '</li>' 

C + + 

} 

e.moveFirst () 

} 

r.text = s 
r. count = c 
return r; 

} 

%> 
<% 

// Write an adapter field as a list of read-only values, 
function WriteListValues (f ) 

{ 

obj=ListValues (f ) 

%> 

<ulx%=obj .text%x/ul> 

<% 
} 

%> 

Esempio 16 



Vedere anche: Tipo AdapterFieldValuesList (page B-ll), proprieta Values e ValuesList 
del tipo AdapterField (page B-7) 

Questo esempio scrive un campo dell'adapter come un gruppo di elementi 
< input type="radio">. 

<% 

// Return an object that defines HTML radio buttons for an adapter field. 
// The returned object has the following elements: 

// 

// text - string containing the <input type=radio> elements. 
// count - the number of elements. 

// 

// Use as follows to define a radio button group with three columns and no additional 
// attributes: 

// obj=RadioGroup(f , 3, ") 
// Response. Writefobj .text) 

// 

function RadioGroup (f , cols ,attr) 

{ 

var s=' ' 
var v=' ' 
var n=' ' 
var c=0; 
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var nm=f .InputName 

if (f .ValuesList == null) 

{ 

s+= '<input type="radio"' 

if (f.IsEqual(true) ) s+= ' checked' 

s += ' value="true" ' + ' name="' + nm + "" 

if (attr!=' ') s+= ' ' + attr 

s += 'x/input>\r\n' 

c = 1 

} 

else 

{ 

s += '<tablextr>' 

var e = new Enumerator (f. ValuesList .Records) 

for (; !e.atEnd(); e.moveNext ( ) ) 

{ 

if (c % cols == && c != 0) s += '</trxtr>' 

s+= '<tdxinput type="radio"' 

v = f. ValuesList. Value; 

var checked 

if (f. Values == null) 

checked = (f . isEqual (v) ) 
else 

checked = f. Values. HasValue(v) 
if (checked) 

s+= ' checked' 
n = f .ValuesList .ValueName; 
if (n==") 
{ 

n = v 
} 

s += ' value="' + v + "" + ' name="' + nm + "" 

if (attr! = ") s+= ' ' + attr 

s +='>'+ n + '</inputx/td>\r\n' 

C + + 

} 

e.moveFirst () 

s += '</trx/table>' 

} 

r = new Object; 
r.text = s 
r. count = c 
return r; 

} 

%> 
<% 

// Write an adapter field as a radio button group 
function WriteRadioGroup (f, cols, attr) 

{ 

obj=RadioGroup(f, cols, attr) 
Response. Write (obj .text) ; 

} 

%> 
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Vedere anche: AdapterField type's DisplayStyle, ViewMode, and InputStyle properties 
(pageB-7) 

Questo esempio genera del codice HTML per un campo dell'adapter in base ai valori 
delle proprieta InputStyle, DisplayStyle e ViewMode. 

<% 

function WriteFieldff ) 

{ 

Mode = f. ViewMode 
if (Mode == 'Input') 
{ 

Style = f. InputStyle 

if (Style == 'SelectMultiple' II Style == 'Select') 

WriteSelectOptions (f ) 
else if (Style == 'CheckBox') 

WriteCheckBoxGroup (f , 2, ") 
else if (Style == 'Radio') 

WriteRadioGroup (f , 2, ") 
else if (Style == 'TextArea') 
{ 

%> 

<textarea wrap=0FF name="<l=f . lnputNamel>"><%= f.EditText %></textarea> 

<% 

} 

else if (Style == 'Passwordlnput') 
{ 

%> 

<input type= "password" name="<%=f . InputName%>"/> 

<% 

} 

else if (Style == 'File' ) 
{ 

%> 

<input type="file" name="<%=f . InputName%>" /> 

<% 

} 

else 
{ 

%> 

<input type="input" name="<%=f . InputNamel>" value="<%= f.EditText %>"/> 




else 
{ 

Style = f .DisplayStyle 
if (Style == 'List') 
WriteListValues (f ) 
else if (Style == 'Image') 
{ 

%> 
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<img src="<%=(f. Image !=null) ? f. Image. AsHREF : "%>" alt="<%=f .DisplayText%>"> 

<% } 

else 

Response. Write ( '<p>' + f .DisplayText + '</p>') 

} 

} 

%> 

Esempio18 



Vedere anche: oggetto Page (page B-17), proprieta Title dell'oggetto Application 
(pageB-15) 

Questo esempio utilizza proprieta dell'oggetto Application e dell'oggetto Page per 
generare un'intestazione di pagina. 

<html> 
<head> 
<title> 

<%= Page. Title %> 
</title> 
</head> 
<body> 

<hl><%= Application. Title %></hl> 
<h2><%= Page. Title %></h2> 

Esempio 19 



Vedere anche: oggetto EndUser (page B-16) 

Questo esempio utilizza le proprieta dell'oggetto EndUser per visualizzare il nome, il 
comando di login e il comando di logout di un utente. 

<% if (EndUser. Logout != null) 

{ 

if (EndUser. DisplayName != ") 

{ 

%> 

<hl>Welcome <l=EndUser. DisplayName %></hl> 

<% } 

if (EndUser. Logout .Enabled) { 

%> 

<a href="<%=EndUser. Logout .AsHREFl>">Logout</a> 

<% } 

if (EndUser. LoginForm. Enabled) { 

%> 

<a href = " <%=EndUser . LoginForm. AsHREF%> " >Login</a> 

<% } 
} 

%> 
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Vedere anche: Tipo Module (page B-12) 

Questo esempio elenca gli oggetti in un modulo in grado di gestire script . 

<% 

// Write an HTML table list the name and classname of all scriptable objects in a module, 
function ListModuleObjects (m) 

{ 

%> 

<px/p> 

<table border="l"> 

<tr> 

<th colspan="2"x%=m.Name_ + ': ' + m.ClassName_%x/th> 

</tr> 

<% 

var e = new Enumerator (m. Objects) 
for (; !e.atEnd(); e.moveNext ( ) ) 
{ 

%> 

<tr> 
<td> 

<%= e.item() .Name. + ': ' + e. item) ) .ClassName_ %> 

</td> 

</tr> 




%> 

</table> 

<% 

} 

%> 

Esempio 21 



Vedere anche: proprieta DisplayStyle e Enabled del tipo AdapterAction (page B-4) 

Questo esempio genera del codice HTML per un'azione dell'adapter in base alia 
proprieta DisplayStyle dell'azione. 

<% 

// Write HTML for an adapter action using the DisplayStyle property. 

// 

//a - action 

// cap - caption. If blank the action's display label is used. 
// fm - name of the HTML form 

// p - page name to goto after action execution. If blank, the current page is used. 

// 

// Note that this function does not use the action's Array property. Is is assumed that 
// the action has a single command. 

// 

function WriteAction (a, cap, fm, p) 

{ 
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if (cap == ") 

cap = a.DisplayLabel 
if (p == ") 

p = Page. Name 
Style = a.DisplayStyle 
if (Style == 'Anchor' ) 
{ 

if (a. Enabled) 

{ 

// Do not use the href property. Instead, submit the form so that HTML form 
// fields are part of the HTTP request. 

%> 

<a href =" "onclick="<%=fml>. act . value=' 

<%=a.LinkToPage (p) . AsFieldValuel>' ;<%=fm%> . submit ( ) ; return false; "> 
<%=cap%x/a> 

<% 

} 

else 
{ 

%> 

<axl=cap%x/a> 

<% 

} 

} 

else 
{ 

%> 

<input type=" submit 11 value="<%= cap%>" 

onclick="<%=fml>. act . value= '<%=a .LinkToPage (p) . AsFieldValue%>' "> 

<% 

} 




Esempio 22 

Vedere anche: proprieta HiddenFields, HiddenRecordFields, e Mode del tipo Adapter 
(page B-2) 

Questo esempio genera una tabella HTML per aggiornare piu record di dettaglio. 

<% 

vltemsAdapter=Modules . DM. It ems Adapter 
vOrdersAdapt er=Modules . DM . OrdersAdapter 
vOrderNo=vOrdersAdapter.OrderNo 
vCustNo=vOrdersAdapter.CustNo 
vPrevRow=vOrdersAdapter . PrevRow 
vNextRow=vOrdersAdapter.NextRow 
vRefreshRow=vOrdersAdapter.RefreshRow 
vApply=vOrdersAdapter. Apply 
vItemNo=vItemsAdapter. ItemNo 
vPartNo=vltemsAdapter.PartNo 
vDiscount=vItemsAdapter. Discount 
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vQty =vlt emsAdapt er . Qty 
%> 

<!-- Use two adapters to update multiple detail records. 

The orders adapter is associated with the master dataset. 

The items adapter is associated with the detail dataset. 

Each row in a grid displays values from the items adapter. One 

column display an <input> element for editing Qty. The apply button 

updates the Qty value in each detail record. --> 

<!-- Display the order number and customer number values. --> 
<h2>OrderNo: <%= vOrderNo.DisplayText %></h2> 
<h2>CustNo: <% vCustNo.DisplayText %></h2> 

<% 

// Put the items adapter in edit mode because this form updates 
// the Qty field. 
vltemsAdapter.Mode = 'Edit' 

%> 

<form name="AdapterForml" method="post"> 

<!-- Define a hidden field for submitted the action name and parameters --> 
<input type="hidden" name="__act"> 

<% 

// Write hidden fields containing state information about the 
// orders adapter and items adapter, 
if (vOrdersAdapter.HiddenFields != null) 

vOrdersAdapter.HiddenFields.WriteFields (Response) 
if (vltemsAdapter.HiddenFields != null) 

vltemsAdapter.HiddenFields .WriteFields (Response) 

// Write hidden fields containing state information about the current 
// record of the orders adapter, 
if (vOrdersAdapter.HiddenRecordFields != null) 
vOrdersAdapter.HiddenRecordFields. WriteFields (Response) %> 

<table border="l"> 

<tr> 

<th>ItemNo</th> 
<th>PartNo</th> 
<th>Discount</th> 
<th>Qty</th> 
</tr> 

<% 

var e = new Enumerator (vltemsAdapter. Records) 
for (; !e.atEnd(); e.moveNext ( ) ) 

{ %> 

<tr> 

<tdx%=vItemNo.DisplayText%x/td> 
<tdx%=vPartNo.DisplayText%x/td> 
<tdx%=vDiscount .DisplayText%x/td> 

<tdxinput type="text" name="<l=vQty . InputName%>" value="<%= vQty.EditText %>" ></td> 
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</tr> 

<% 

// Write hidden fields containing state information about each record of the 

// items adapter. This is needed by the items adapter when updating the Qty field. 

if (vltemsAdapter.HiddenRecordFields != null) 
vltemsAdapter.HiddenRecordFields .WriteFields (Response) 

} 

%> 

</table> 

<px/p> 
<table> 

<tdxinput type="submit" value="Prev Order" 

onclick= 11 Adapt erForml . act . value= '<l=vPrevRow.LinkToPage (Page. Name) . AsFieldValue%>' "></td> 

<tdxinput type="submit" value="Next Order" 

onclick= 11 Adapt erForml . act . value= '<%=vNextRow.LinkToPage (Page. Name) . AsFieldValue%>' "></td> 

<tdxinput type="submit" value="Refresh" 

onclick= 11 Adapt erForml . act .value= '<%=vRefreshRow.LinkToPage (Page. Name) .AsFieldValue%>' "></ 

td> 

<tdxinput type="submit" value="Apply" 
onclick= "Adapt erForml . act . value= '<%=vApply .LinkToPage (Page. Name) . AsFieldValuel>' "></ 

td> 

</table> 
</form> 



Guida di riferimento agli script lato server di WebSnap B-39 



Esempi JScript 



B-40 Bookname goes here 



Indice 



Simboli 

... (puntini) pulsanti 19-23 

Numeri 

80x87, coprocessori A-3 

A 

a capo automatico 6-8 

-a, opzione del compilatore A-6 

abort, funzione A-ll 

Abort, procedura 

prevenzione delle 
modifiche 22-21 
AbortOnKeyViol, 
proprieta 24-54 
AbortOnProblem, 
proprieta 24-54 
About, finestra 57-2 

aggiunta a controlli 
ActiveX 43-5 

aggiunta di proprieta 57-5 

esecuzione 57-6 
acceleratori 8-36 
acceleratori di tastiera 9-6 
Access, tabelle 

transazioni locali 24-33 
accesso 

oggetti volatili A-6 

regioni di memoria A-6 

union A-5 
accesso ai dati 

componenti 7-16, 18-1 
thread 11-5 

meccanismi 7-16 - 7-17, 18-1 
- 18-2, 22-2 

multipiattaforma 17-7, 18-2 
accordo di licenza 17-17 
Acquire, metodo 11-8 
action bands 8-20 
Action client, definizione 8-18 
action editor 

aggiunta di azioni 33-5 

cambio di azioni 33-6 
Action List editor 8-20 
Action Manager 8-20, 8-21, 8-23 

definizione 8-19 
Actions, proprieta 33-5 
Active Documents 38-11, 38-15 



Vedi anche IoleDocumentSite, 
interfaccia 
active scripting 34-34 
Active Server Objects 42-1 - 
42-9 

creazione 42-2-42-8 

debug 42-8 - 42-9 

registrazione 42-8 

server in-process 42-7 

server out-of-process 42-7 
Active Server Objects, 

wizard 42-2-42-3 
Active Server Pages Vedere ASP 
Active Template Library Vedere 

ATL 
Active, proprieta 

dataset 22-4 

sessioni 24-18,24-19 

socket client 37-7 

socket server 37-8 
ActiveAggs, proprieta 27-14 
ActiveFlag, proprieta 20-20, 
20-21 

ActiveForms 43-1, 43-6 - 43-7 
applicazioni multi-tier 29-32 
come applicazioni Web 

database 29-32 
creazione 43-2 
e InternetExpress 29-31 
wizard 43-6 - 43-7 
ActiveX 38-14 - 38-15, 43-1 
applicazioni Web 38-14, 

43-1,43-17-43-19 
confronto con ASP 42-7 
e InternetExpress 29-31 - 

29-32 
interfacce 38-21 
ActiveX, controlli 
.cab, file 43-19 
17-5, 38-11, 38-14, 43-1 - 43-19 
aggiunta di metodi 43-9 - 
43-11 

aggiunta di proprieta 43-9 - 
43-11 

applicazioni Web 38-14, 

43-1,43-17-43-19 
attivazione di eventi 43-11 
concessione in licenza 43-5, 

43-7-43-8 
creazione 43-2, 43-4 - 43-7 
da controlli VCL 43-4 - 43-7 



data-aware 40-9-40-11, 

43-8, 43-12 - 43-14 
debug 43-17 

distribuzione su Web 43-17 - 

43-19 
elementi 43-2-43-4 
gestione di eventi 43-11 - 

43-12 

importazione 40-4 - 40-5 
interfacce 43-8-43-14 
librerie di tipi 38-18, 43-3 
modello di threading 43-5 
pagine di proprieta 40-7, 

43-3, 43-14 - 43-16 
progettazione 43-4 
proprieta persistenti 43-14 
registrazione 43-16-43-17 
uso di tipi compatibili con 

Automation 43-4,43-8 
wizard 43-4 - 43-6 
wrapper di componenti 40-6, 
40-7-40-8, 40-9-40-11 
_OCX, unit 40-5 
ActiveX, pagina (Component 

palette) 5-8,5-9,40-5 
ActnList, unit 8-31 
adapter 34-2 

adapter dispatcher 34-10, 34-37 
adapter dispatcher, 

richieste 34-38 
adapter produttori di 

pagine B-l 
AdapterPageProducer 34-11 
adattamento delle 

tavolozze 50-5, 50-6 
adattatori 34-5-34-6 
adattatori, dispatcher 34-9 
Add Fields, finestra di 

dialogo 23-5 
Add To Repository, 

comando 7-26 
Add, metodo 

colonne persistenti 19-20 
menu 8-44 
stringhe 4-19 
AddAlias, metodo 24-25 
AddFieldDef, metodo 22-41 
AddFontResource, 

funzione 17-15 
Addlndex, metodo 27-9 
AddlndexDef, metodo 22-41 



Indice 1-1 



Additional, pagina (Component 

palette) 5-7 
AddObject, metodo 4-21 
AddParam, metodo 22-55 
AddPassword, metodo 24-22 
AddRef, metodo 38-4 
Address, proprieta, 

TSocketConnection 29-25 
AddStandardAlias, 

metodo 24-26 
AddStrings, metodo 4-20 
ADO 22-2, 25-1, 25-2 

componenti 25-1 - 25-20 

panoramica 25-1 - 25-2 
datastore 25-2,25-4 
distributori di risorse 44-6 
distribuzione 17-7 
provider 25-3,25-4 
transazioni implicite 25-6 - 
25-7 

ADO, comandi 25-7, 25-17 - 
25-20 
annullamento 25-19 
asincroni 25-19 
esecuzione 25-18 - 25-19 
iterazione 21-13 
parametri 25-20 
reperimento dati 25-19 - 

25-20 
specifica 25-18 
ADO, connessioni 25-2 - 25-9 
asincrone 25-5 
connessione a datastore 25-2 
-25-7 

esecuzione di comandi 25-6 
eventi 25-7-25-9 
timeout 25-5-25-6 
ADO, dataset 25-9 - 25-17 
aggiornamenti batch 25-12 - 

25-15 
connessione 25-10 
file dati 25-15 - 25-16 
prelievo asincrono 25-11 - 

25-12 
ricerche basate su 

indice 22-29 
ADO, oggetti 25-1 

oggetto Connection 25-4 - 

25-5 

RDSDataSpace 25-17 
Recordset 25-9,25-10-25-11 

ADO, pagina (Component 
palette) 5-8, 18-2, 25-1 

ADT, campi 23-24, 23-24 - 23-26 



campi persistenti 23-25 - 

23-26 
esplicitazione 19-24 
visualizzazione 19-24, 23-24 
- 23-25 
ADTG, file 25-15 
AfterApplyUpdates, 
evento 27-34, 28-8 
AfterCancel, evento 22-22 
AfterClose, evento 22-4 
AfterConnect, evento 21-3, 
29-28 

AfterConstruction 13-15 
AfterDelete, evento 22-21 
AfterDisconnect, evento 21-4, 
29-28 

AfterDispatch, evento 33-6, 33-9 
AfterEdit, evento 22-18 
AfterGetRecords, evento 28-8 
Afterlnsert, evento 22-19 
AfterOpen, evento 22-4 
AfterPost, evento 22-21 
AfterScroll, evento 22-6 
aggancio 6-4 

AggFields, proprieta 27-15 
aggiornamenti batch 25-12 - 
25-15 
annullamento 25-15 
applicazione 25-14 
aggiornamenti in cache 27-17 - 
27-26 
ADO 25-12-25-15 
annullamento 25-15 
applicazione 25-14 
BDE 24-33-24-50 

aggiornamento dataset a 

solalettura 24-11 
applicazione 24-11, 24-35 
tabelle multiple 24-42, 
24-46 

gestione degli errori 24-39 

- 24-41 

dataset client 18-10 - 18-15, 
27-17, 27-21 - 27-26 
aggiornamento dataset a 

solalettura 24-11 
applicazione 24-11, 27-22 

- 27-23 

tabelle multiple 24-42, 
24-46 
errori di 
aggiornamento 27-25 - 
27-26, 28-12 
transazioni 21-7 
oggetti update 27-20 



panoramica 27-18-27-19 

provider 28-8 

relazioni master/ 
detail 27-20 
aggiornamenti in cascata 28-6 
aggiunta di record 22-20 
Aggregates, proprieta 27-12, 

27-14 
aggregati di 
manutenzione 27-12 - 27-15 

specifica 27-12-27-13 
aggregazioni 

COM 38-9-38-10 

dataset client 27-12 - 27-15 
aggregazioni di 
manutenzione 18-16 

campi di aggregazione 23-10 

operatori di riepilogo 27-13 

subtotali 27-13 

valori 27-14 
alias 

BDE 24-3,24-14,24-25- 
24-27 
cancellazione 24-27 
creazione 24-25-24-26 
local 24-26 
specifica 24-14,24-15 
Type Library editor 39-10, 
39-18 

AliasName, proprieta 24-14 
Align, proprieta 8-4 

barre di stato 9-17 

controlli di testo 6-7 

pannelli 8-47 
Alignment, proprieta 9-7 

barre di stato 9-17 

campi 23-12 

controlli memo data- 
aware 19-9 

controlli memo e rich 
edit 9-3 

grigliedati 19-22 

griglie decisionali 20-13 

intestazioni di colonna 19-23 
allineamento A-3 

campi di bit e A-6 

membri della struttura A-6 

word A-6 
Allow AllUp, proprieta 9-9 

pulsanti di scelta rapida 8-48 

pulsanti strumento 8-51 
AllowDelete, proprieta 19-31 
AllowGrayed, proprieta 9-9 
Allowlnsert, proprieta 19-31 
alTop, costante 8-47 



1-2 Guida alia programmazione 



ambiente di sistema operativo 

stringhe, modifica 
permanente A-ll 
ambienti A-ll 
animazione, controlli 9-20 
anni bisestili 55-9 
annidati, dichiaratori A-6 
ANSIC 

caratteri multibyte A-2 

diagnostica A-l 

diagnostici A-8 

formati data e ora A-12 

funzione main A-2 

specifiche di 
implementazione A-l 

standard, 
implementazione A-l 

trattino, 
interpretazione A-10 
ANSI, set di caratteri 16-3 

estesi A-2 
AnsiString 52-8 
Apache DLL 17-10 
Apache server, DLL 32-7 

creazione 33-1, 34-9 
Apache, applicazioni 32-7 

creazione 33-1,34-9 

debug 32-11 
apartment, modello di 

threading 41-8 
API Tools 58-1-58-25 

creator 58-3, 58-14 - 58-19 

creazione di file 58-14 - 
58-19 

debug 58-11-58-12 

editor 58-3, 58-13 - 58-14 

moduli 58-3, 58-13 - 58-14 

notificatori 58-3 

servizi 58-2, 58-8 - 58-14 
Append, metodo 22-19, 22-20 

Insert e 22-19 
AppendRecord, metodo 22-22 
application adapter 34-10 
application server 18-14, 29-1, 
29-12 - 29-18 

apertura di 
connessioni 29-28 

callback 29-18 

identificazione 29-24 

interfacce 29-17 - 29-18, 
29-29 

interruzione di 
connessioni 29-28 

moduli dati multipli 29-21 - 
29-22 



moduli dati remoti 7-25 
registrazione 29-12, 29-22 - 

29-23 
scrittura 29-13 
Application, variabile 8-2 
applicazione socket 

dispatcher 29-10 
applicazioni 

adattamento delle 

tavolozze 50-5, 50-6 
Apache 32-7, 33-1, 34-9 
applicazioni client basate su 

Web 29-31-29-43 
bidirezionali 16-4 
CGI, indipendenti 34-9 
client/server 29-1 

protocolli di rete 24-16 
COM 7-20 
CORBA 31-1 - 31-19 
creazione 8-1 
database 18-1 

multipiattaforma 14-22 
distribuzione 17-1 
file 17-2 

grafiche 45-8, 50-1 
informazioni di stato 9-16 
internationali 16-1 
ISAPI 32-7, 33-1, 34-9 
MDI 7-2 
MTS 7-20 

multipiattaforma 14-1 - 

14-30 
multi-thread 11-1 
multi-tier 29-1 - 29-43 

panoramica 29-3-29-4 
NSAPI 32-7, 33-1, 34-9 
porting in Linux 14-2 - 14-21 
SDI 7-2 

server Web 7-17 
servizio 7-4 

Web Broker 33-1 - 33-21 
Webserver 7-17,34-8 
Win-CGI indipendenti 34-9 
applicazioni basate su file 18-9- 
18-10 

dataset client 27-35 - 27-37 
applicazioni client 
architettura 29-4 
COM 38-3, 38-10, 40-1 - 
40-18 

come applicazioni Web 

server 29-31 
creazione 29-23 - 29-30, 40-1 

- 40-18 
fornitura di query 28-6 



interfacce 37-2 
interfacce utente 29-1 
leggere 29-2,29-31 
librerie di tipi 39-14, 40-2 - 

40- 7 

multi-tier 29-2,29-4 
oggetti transazionali 44-2 
protocolli di rete 24-16 
socket e 37-1 

Web Services 36-17 - 36-18 
applicazioni database 7-16 

basate su file 25-15 - 25-16 

distribuite 7-17 

distribuzione 17-6 

XML e 30-1-30-11 
applicazioni di servizio 7-4 - 
7-9 

codice di esempio 7-5, 7-7 

debug 7-9 

esempio 7-7 
applicazioni distribuite 

CORBA 31-1 - 31-19 
applicazioni GDI 45-8, 50-1 
applicazioni multi-thread 

sessioni 24-13, 24-29 - 24-31 
applicazioni multi-tier 29-1 - 
29-43 

applicazioni Web 29-31 - 
29-43 

creazione 29-32-29-33, 
29-34 - 29-43 
callback 29-18 
componenti 29-2-29-3 
creazione 29-12-29-30 
licenze del server 29-3 
vantaggi 29-2 

applicazioni per console 
VCLe 7-4 

applicazioni remote 
TCP/IP 37-1 

applicazioni server 
architettura 29-5 
COM 38-5 - 38-9, 41-1 - 

41- 18 
interfacce 37-2 
multi-tier 29-5 - 29-12, 29-12 

- 29-18 
registrazione 29-22 - 29-23 
servizi 37-1 

Web Services 36-10 - 36-17 
applicazioni single-tier 18-3 
applicazioni three-tier Vedi 

applicazioni multi-tier 
applicazioni two-tier 18-3, 18-9, 

18-13 



Indice 1-3 



applicazioni Web 

ActiveX 43-17-43-19 

client multi-tier 29-32 
database 29-31-29-43 
Apply, metodo 24-48 
ApplyRange, metodo 22-36 
ApplyUpdates, metodo 14-29, 
24-34 
BDE, dataset 24-37 
dataset client 25-13, 27-7, 
27-22, 27-22 - 27-23, 28-3 
provider 27-22, 28-3, 28-8 
TDatabase 24-36 
TXMLTransformClient 30-10 
AppNamespacePrefix, 

variabile 36-3 
AppServer, proprieta 28-3, 

29-17, 29-29 
Appunti 

azzeramento della 

selezione 6-10 
formati 

aggiunta 52-19 
oggetti grafici 10-3, 19-10 
Arc, metodo 10-4 
architettura 

applicazioni basate su 

BDE 24-1 - 24-2 
applicazioni CORBA 31-1 - 
31-4 

applicazioni database 18-6 - 
18-15, 24-1 - 24-2 
client 29-4 
server 29-5 
multi-tier 29-4,29-5 
Web Broker, applicazioni 
server 33-3 
argomenti 

fmod, funzione A-8 
array 47-3, 47-8 

come argomenti delle 

funzioni 13-24 
come proprieta 13-24 
come tipi restituiti 13-24 
open 13-17 
safe 39-13 
tipi integer A-5 
puntatori A-5 
array of const 13-19 
array, campi 

esplicitazione 19-24 
visualizzazione 19-24, 23-24 
- 23-25 
ARRAYSIZE, macro 13-18 
as, operatore 13-23 



AS_ApplyUpdates, 
metodo 28-3 

AS_ATTRIBUTE 36-7 

AS_DataRequest, metodo 28-3 

AS_Execute, metodo 28-3 

AS_GetParams, metodo 28-3 

AS_GetProviderNames, 
metodo 28-3 

AS_GetRecords, metodo 28-4 

AS_RowRequest, metodo 28-4 

ASCII, codice A-2 

ASCII, tabelle 24-5 

ascolto connessioni 37-3, 37-8 
chiusura 37-8 

ascolto di connessioni 37-9 

ASP 38-14, 42-1 - 42-9 

confronto con ActiveX 42-7 
confronto con Web 

Broker 42-1 
generazione di pagine 42-3 
HTML, documenti 42-1 
limiti nelle prestazioni 42-1 
linguaggio script 38-14, 42-3 
progettazione UI 42-1 

ASP, intrinsics 42-3 - 42-7 
accesso 42-2 - 42-3 
oggetto Application 42-4 
oggetto Request 42-4 - 42-5 
oggetto Response 42-5 - 42-6 
oggetto Server 42-7 
oggetto Session 42-6 

assegnazione del nome a un 
thread 11-13-11-15 

assegnazione, operatori 13-7 

assembler, codice 14-20 

assert, funzione A-8 

Assign Local Data, 
comando 27-15 

Assign, metodo 

elenchi di stringhe 4-20 

AssignedValues, 
proprieta 19-24 

Assign Value, metodo 23-18 

Associate, proprieta 9-6 

as-soon-as-possible, 
disattivazione 29-7 

ATL 38-23-38-25 
file header 38-23 
opzioni 41-9 

traccia delle chiamate 41-9, 
41-18 
atomicita 

transazioni 18-5,44-11 
attivita 



oggetti transazionali 44-20 - 
44-22 
Attributes, proprieta 

parametri 22-48,22-55 

TADOConnection 25-6 
attributi 

editor di proprieta 52-11 
attributi dei campi 

assegnazione 23-14 
attributi di campo 23-14 - 23-15 

in pacchetti dati 28-6 

rimozione 23-15 
attributi di transazione 

impostazione 44-12 

moduli dati 
transazionali 29-16 
attributo di attivazione 

proprieta condivise 44-7 
audio, filmati 10-33 
auto_ptr 12-6 

AutoCalcFields, proprieta 22-24 
AutoComplete, proprieta 29-8 
auto-dispatch, 

componenti 36-12 
AutoDisplay, proprieta 19-10, 

19-11 

AutoEdit, proprieta 19-5 

AutoHotKeys property 8-36 

Automation 

Active Server Objects 42-2 
binding anticipato 38-19 
binding differito 41-14 
compatibilita dei tipi 39-12, 

41-16-41-17 
descrizioni dei tipi 38-13 
interfacce 41-13-41-15 
interfaccia IDispatch 41-14 
ottimizzazione 38-19 

Automation controller 40-1, 
40-13 - 40-17, 41-14 
creazione di oggetti 40-13 - 
40-14 

esempio 40-11-40-13 
eventi 40-15-40-17 
interfacce dispatch 40-14 - 
40-15 

interfacce duali 40-14 
Automation server 38-11 
Vedi anche COM, oggetti 
accesso a oggetti 41-14 
librerie di tipi 38-18 
Automation, oggetti 

Vedi anche COM, oggetti 
wizard 41-4-41-9 
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wrapper di componenti 40-8 
-40-9 
esempio 40-11-40-13 
Automation, server 38-13 
AutoPopup, proprieta 8-53 
AutoSelect, proprieta 9-4 
AutoSessionName, 

proprieta 24-31,33-19 
AutoSize, proprieta 8-5, 9-3, 

17-15, 19-9 
.avi, clip 9-20, 10-31 
.avi,file 10-34 
.avi, filmati 10-34 
azioni 8-25-8-32 

aggiornamento 8-29 
classi di azioni 8-29 
client 8-19 

definizione 8-18,8-19 

destinatario 8-20 

esecuzione 8-27 

predefinite 8-30 

registrazione 8-31 
azioni, elementi 

dispatch 34-41 
azioni, richieste 34-39 

B 

Background 8-22 
backslash, caratteri (\) 

file include A-7 
bande di azioni 

definizione 8-18 
Bands, proprieta 8-52, 9-10 
barre di avanzamento 9-17 
barre di scorrimento 9-5 

finestre di testo 6-8 
barre di separazione 9-7 
barre di separazione 

(menu) 8-36 
barre di stato 9-16 

internazionalizzazione 16-9 

owner draw 6-12 
barre strumenti 8-45, 9-9 

aggiunta 8-49-8-51 

aggiunta di pannelli 
come 8-47-8-49 

creazione 8-20 

disattivazione di 
pulsanti 8-50 

inserimento di pulsanti 8-47 
- 8-49, 8-50 

liste di azioni 8-19 

menu contestuali 8-52 

occultamento 8-53 

owner-draw 6-12 



progettazione 8-45 - 8-53 
pulsanti di scelta rapida 9-8 
strumento predefinito di 

disegno 8-48 
trasparenti 8-50,8-52 

BaseCLX 

classi di eccezioni 12-17 
definizione 4-1, 14-6 

Basic Object Adapter Vedere 
BOA 

batch, file 

esecuzione A-12 
Linux 14-14 

BatchMove, metodo 24-8 

BDE 

distributori di risorse 44-6 
BDE Administration, 

utilita 24-15, 24-57 
BDE, dataset 18-1, 22-2, 24-2 - 

24-13 

applicazione aggiornamenti 

in cache 24-37 
copia 24-52 
database 24-3 - 24-4 
operazioni batch 24-50 - 

24-55 
sessioni 24-3-24-4 
supporto decisionale, 
componenti e 20-5 
supporto per database 

locali 24-5-24-8 
tipi 24-2 
BDE, pagina (Component 

palette) 5-8,18-1 
BeforeApplyUpdates, 

evente 27-34,28-8 
BeforeCancel, evento 22-22 
BeforeClose, evento 22-4 
BeforeConnect, evento 21-3, 
29-28 

BeforeDelete, evento 22-21 
BeforeDestruction, 

metodo 13-15 
BeforeDisconnect, evento 21-4, 

29-28 

BeforeDispatch, evento 33-5, 
33-7 

BeforeGetRecords, evento 28-8 
Beforelnsert, evento 22-19 
BeforeOpen, evento 22-4 
BeforePost, evento 22-21 
BeforeScroll, evento 22-6 
BeforeUpdateRecord, 

evento 24-34, 24-42, 27-24, 

28-12 



BEGIN_MESSAGE_MAP, 

macro 51-4, 51-8 
BeginAutoDrag, metodo 51-14 
BeginDrag, metodo 6-1 
BeginRead, metodo 11-9 
BeginTrans, metodo 21-7 
Begin Write, metodo 11-9 
bevel 9-20 
Beveled 9-7 

bidirezionali, applicazioni 16-4 

metodi 16-7-16-8 

proprieta 16-6 
bidirezionali, cursor 22-51 
bilanciamento del carico 31-3 
Bind, metodo 

TAutoDriver 40-14 
binding anticipato 

Automation 38-19,41-13 

COM 38-18 
binding di dati 43-12 
binding differito 31-15 

Automation 41-13,41-14 
binding dinamico 31-15 

CORBA 31-4,31-16 

DII 31-4 
binding statico 

CORBA 31-14 
bit, acmpi A-6 
bit, campi 

allineamento A-6 

ordine di allocazione A-6 

superamento dei limiti della 
word A-6 
bitmap 9-20, 10-19 - 10-20, 50-4 

aggiunta a component 45-15 

aggiunta ai componenti 52-4 

aggiunta di scorribili 10-18 

associazione a stringhe 6-13 

barre strumenti 8-50 

caricamento 50-5 

controlli grafici e 54-4 

disegno 10-19 

disegno di superfici 50-4 

distruzione 10-22 

eventi draw-item 6-16 

fuori schermo 50-6 - 50-7 

impostazione dello stato 
iniziale 10-18 

internazionalizzazione 16-10 

pennelli 10-10 

proprieta dei pennelli 10-8, 
10-10 

scorrimento 10-18 

sostituzione 10-21 

temporanee 10-18, 10-19 
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vuote 10-19 
bitmap a scorrimento 10-18 
bitmap fuori schermo 50-6 - 
50-7 

bitmap, oggetti 10-3 
bitmap, pulsanti 9-8 
bitmaps 

associazione a stringhe 4-21 

in frame 8-16 
bitwise, operatori 

integer con segno e A-5 
BLOB 19-10 

memorizzazione in 
cache 24-4 
BLOB, campi 19-3 

acquisizione su 
richiesta 28-6 

ottenimento di valori 24-4 

visualizzazione di 
grafici 19-10 

visualizzazione di 
valori 19-10 
blocchi esclusivi 

tabelle 24-6 
blocco di oggetti 

annidamento di 
chiamate 11-8 

thread 11-8 
blocco di terminazione 12-13 
BlockMode, proprieta 37-9, 

37-10, 37-11 
bmBlocking 37-11 
BMPDlg, unit 10-22 
bmThreadBlocking 37-9, 37-11 
BOA 31-2, 31-5 

BOA_init 31-8 

conflitti di thread 31-12 

inizializzazione 31-14 

obj_is_ready, metodo 31-8 
Bof, proprieta 22-6, 22-7, 22-9 
bookmark 

supporto in base al tipo di 
dataset 22-9 
Bookmark, proprieta 22-10 
BookmarkValid, metodo 22-10 
Boolean, campi 19-2 
BorderWidth, proprieta 9-14 
bordi 

pannelli 9-14 
bordi, disegno 10-6 
Borland Database Engine 7-16, 
18-1, 22-2, 24-1 

aggiornamenti in 
cache 24-33-24-50 



errori di 
aggiornamento 24-39 
alias 24-3, 24-14, 24-17, 24-25 
- 24-27 
cancellazione 24-27 
creazione 24-25-24-26 
disponibilita 24-26 
query eterogenee 24-10 
specifica 24-14,24-15 
apertura di connessioni a 

database 24-20 
applicazioni Web 17-10 
chiamate alle API 24-1, 24-4 
chiusura delle 

connessioni 24-20 
connessione a database 24-17 
connessione predefinita, 

proprieta 24-19 
dataset 24-2 
distribuzione 17-8, 17-9, 

17-17 
driver 24-1,24-14 
gestione delle 

connessioni 24-20-24-22 
nomi di driver 24-14 
ODBC, driver 24-17 
operazioni batch 24-50 - 
24-55 

programmi di utilita 24-56 - 
24-57 

query eterogenee 24-9 - 
24-10 

recupero dei dati 22-50, 24-2, 
24-10 

requisiti di licenza 17-17 

sessioni 24-17 

tipi di tabelle 24-5 

transazioni implicite 24-31 
Borland, contatti 1-3 
BorlandlDEServices, 

variabile 58-8,58-24 
BoundsChanged, metodo 51-14 
.bpi, file 15-2, 15-14 
.bpk, file 15-2, 15-7, 15-8 
.bpl, file 15-1, 15-14, 17-3 
briefcase, modello 18-15 
Broadcast, metodo 51-9 
broker di dati 27-27, 29-1 
brokering delle 

connessioni 29-27 
Brush, proprieta 9-20, 10-4, 

10-8, 50-3 
BrushCopy, metodo 50-3, 50-7 
buffer, file con A-9 



business-to-business, 
comunicazioni 35-1 
ButtonAutoSize, 
proprieta 20-10 
ButtonStyle, proprieta 
griglie dati 19-22, 19-23, 
19-24 
ByteType 4-23 

c 

C++ e Object Pascal 
argomenti delle 

funzioni 13-8, 13-20, 13-24 
assegnazione 13-7 
chiamata a metodi 

virtuali 13-10,13-15 
copia di oggetti 13-6 
costruttori 13-22 
costruttori di copia 13-7 
costruzione di oggetti 13-8 
differenze 13-15,13-20 
distruzione di oggetti 13-13 
inizializzazione delle 

classi 13-12 
parallelismi nel 

linguaggio 13-17 
parametri senza tipo 13-17 
passaggio per 

riferimento 13-17 
riferimenti 13-6 
RTTI 13-23 
tipibool 13-20 
C++, gestione delle 

eccezioni 12-1 
C++, modello a oggetti 13-1 
CacheBLOB, proprieta 24-4 
CachedUpdates, 

proprieta 14-29,24-34 
calendari 55-1 - 55-14 

aggiunta di date 55-6-55-11 
come renderli a sola 
lettura 56-3-56-5 
definizione di proprieta ed 

eventi 55-3, 55-8, 55-12 
ridimensionamento 55-4 
selezione del giorno 

corrente 55-11 
spostamento nei 55-11- 
55-14 
callback 

applicazioni multi-tier 29-18 

limiti 29-11, 29-12 
oggetti transazionali 44-28 
calloc, funzione A-ll 
campi 23-1 - 23-29 
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a sola lettura 19-6 
aggiornamento dei 

valori 19-5 
aggiunta a schede 10-27 - 

10-29 

assegnazione di valori 22-23 
attivazione 23-17 
cambio dei valori 19-6 
colonne persistenti e 19-19 
database 56-6, 56-7 
elenco 21-14 
formati predefiniti 23-16 
inserimento dati 22-19, 23-15 
limitazione della validita dei 

dati 23-22-23-23 
nascosti 28-5 
opzioni reciprocamente 

esclusive 19-2 
proprieta 23-1 
record del messaggio 51-7 
reperimento dati 23-18 
tipi di dati astratti 23-24 - 

23-29 
valori nulli 22-22 
valori predefiniti 23-22 
visualizzazione di 
valori 19-11,23-18 

campi array 

campi persistenti 23-27 

campi BLOB 19-2 

campi booleani 19-14 

campi calcolati 22-24, 23-6 
assegnazione di valori 23-8 
campi di consultazione 

e 23-10 
dataset client 27-11 - 27-12 
definizione 23-7 - 23-9 

campi chiave 22-34 
multipli 22-33,22-34 

campi dati 23-6 
definizione 23-7 

campi del dataset 23-27 - 23-28 

campi di aggregazione 23-6, 
27-15 

definizione 23-10-23-11 
visualizzazione 23-11 

campi di array 23-26 - 23-27 

campi di classe 

dichiarazione 54-6 

campi di classi 54-4 

campi di consultazione 19-13, 
23-6 

cache dei valori 23-10 
definizione 23-9-23-10 



fornitura di valori da 

programma 23-10 
in griglie dati 19-23 
performance 23-10 
specifica 19-23 
campi di oggetti 23-24 - 23-29 

tipi 23-24 
campi di riferimento 23-28 - 
23-29 

campi dinamici 23-2 - 23-3 
campi memo 19-2, 19-9 - 19-10 

rich edit 19-10 
campi nascosti 28-5 
campi numerici 

formattazione 23-16 
campi ora 

formattazione 23-16 
campi persistenti 19-17, 23-3 - 

23- 17 

ADT, campi 23-25 - 23-26 
assegnazione dei nomi 23-6 
campi array 23-27 
campi del dataset 22-39 
cancellazione 23-11 
commutazione a 

dinamici 23-4 
creazione 23-4 - 23-5, 23-5 - 

23-11 

creazione tabelle 22-41 
definizione 23-5 - 23-11 
elenco 23-5 
ordinamento 23-5 
pacchetti dati e 28-5 
proprieta 23-11-23-16 
tipispeciali 23-5,23-6 

campi stringa 9-18 
dimensioni 23-6 

campi, definizioni 22-40, 22-41 

campo, oggetti 
proprieta 

condivisione 23-14 

CanBePooled, metodo 44-10 

Cancel, metodo 22-19, 22-22, 
25-19 

Cancel, proprieta 9-8 
CancelBatch, metodo 14-29, 

25-13, 25-15 
cancellazioni in cascata 28-6 
CancelRange, metodo 22-36 
CancelUpdates, metodo 14-29, 

24- 34, 25-13, 27-7 
CanModify, proprieta 

dataset 19-5, 22-17, 22-39 
griglie dati 19-28 
query 24-11 



canvas 45-7,50-3 

aggiornamento dello 

schermo 10-2 
aggiunta di figure 10-11 - 

10-12, 10-14 
copia di immagini 50-7 
disegno di linee 10-6, 10-10 - 
10-11, 10-29-10-30 
cambio dello spessore 

della penna 10-6 
gestori di evento 10-27 
disegno e tracciamento 10-4 
panoramica 10-1 - 10-4 
proprieta comuni, 

metodi 10-4 
strumenti di disegno 

predefiniti 54-6 
tavolozze 50-5 - 50-6 
tracciamento e disegno 10-23 
Canvas, proprieta 9-20, 45-8 
Caption, proprieta 

caselle di gruppo e gruppi di 

opzioni 9-14 
etichette 9-4 
griglie decisionali 20-13 
intestazioni di colonna 19-23 
TForm 9-16 
voci non valide 8-34 
caratteri 47-2 
multibyte A-2 
newline A-9 
null A-9 

punto decimale A-7 
wide A-4 
caratteri estesi 16-3 
caratteri ideografici 16-3 

abbreviazioni 16-9 
caselle combinate 9-12, 14-8, 
19-2, 19-12 
consultazione 19-23 
data-aware 19-11-19-14 
owner-draw 6-12 

eventi measure-item 6-15 
caselle combinate di 
consultazione 19-2, 19-12 - 
19-14 

campi di consultazione 19-13 

in griglie dati 19-23 

riempimento 19-23 

sorgenti dati 
secondarie 19-13 
caselle di controllo 9-9, 9-11 

data-aware 19-14-19-15 

TDBCheckBox 19-2 
caselle di gruppo 9-14 
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caselle di riepilogo 9-11, 19-2, 
19-12, 55-1 
data-aware 19-11-19-14 
memorizzazione di proprieta 

esempio 8-9 
owner-draw 6-12 

eventi draw-item 6-16 
eventi measure-item 6-15 
riempimento 19-11 
rilascio di elementi 6-3 
trascinamento di 
elementi 6-2, 6-3 
caselle di riepilogo di 
consultazione 19-2, 19-12 - 
19-14 

campi di consultazione 19-13 
sorgenti dati 
secondarie 19-13 
caselle grafiche 19-2 
catch, istruzione 12-2, 12-3, 
12-17 

CComCoClass 38-24, 41-3, 41-4, 
42-2 

CComModule 38-24 
CComObjectRootEx 38-24 - 

38-25, 41-3, 41-4, 42-2 
CellDrawState, funzione 20-13 
celle (griglie) 9-18 
CellRect, metodo 9-18 
Cells, funzione 20-13 
Cells, proprieta 9-18 
CellValueArray, funzione 20-13 
centralizzazione di oggetti 
moduli dati remoti 29-8 - 
29-9 

cerchi, disegni 54-10 

CGI, applicazioni 32-6, 32-7 

creazione 33-2, 34-9 
Change, metodo 56-12 
ChangeCount, proprieta 14-29, 

24-34, 27-6 
ChangedTableName, 

proprieta 24-55 
CHANGEINDEX 27-8 
character 

wide A-4 
Chart Editing, finestra di 

dialogo 20-16-20-19 
Chart FX 17-5 
CHECK, vincolo 28-13 
Checked, proprieta 9-9 
CheckSynchronize routine 11-5 
chiavi di licenza 43-7 
chiavi parziali 



impostazione degli 
intervalli 22-34 

ricerca 22-31 
ChildName, proprieta 29-30 
Chord, metodo 10-4 
ciclo del messaggio 

thread 11-5 
class factory 

supportoATL 38-24 
classi 45-2, 45-3, 46-1, 47-2 

accesso 46-4-46-8,54-7 

antenato 46-3-46-4 

astratte 45-3 

creazione 46-1 

definizione 45-13,46-2 

derivazioe di nuove 46-2 

derivazione di nuove 46-3 

discendenti 46-3-46-4 

editor di proprieta 
come 52-8 

gerarchia 46-4 

istanziazione 46-2, 48-2 

limitazione dell'accesso 46-5 

passaggio come 
parametri 46-11 

predefinite 46-4 

proprieta come 47-2 

sezione private 46-5 

sezione protected 46-7 

sezione public 46-7 

sezione published 46-8 

supporto per Object 
Pascal 13-16 
classi antenato 46-3 - 46-4 

predefinite 46-4 
classi astratte 45-3 
classi base 

costruttori 13-11 
classi creatore 

CoClass 40-6, 40-13 - 40-14 
classi derivate 46-3 - 46-4 
classi in stile VCL 13-1 

eredita 13-2 
classi richiamabili 

creazione 36-13 

classid, operatore 13-24 

Classlnfo, metodo 13-23 
ClassName, metodo 13-23 
ClassNamels, metodo 13-23 
ClassParent, metodo 13-23 
ClassType, metodo 13-23 
Clear, metodo 

campi 23-18 

elenchi di stringhe 4-20, 4-21 
ClearSelection, metodo 6-10 



Click, metodo 51-14 

ridefinizione 48-6, 55-13 
client base 44-2 

client leggeri, applicazioni 29-2, 
29-31 

client Vedere applicazioni client 
client, applicazioni 

CORBA 31-2, 31-14 - 31-17 
client, socket 

oggetti socket 37-6 
client/server, applicazioni 7-16 
Clipboard 6-8, 6-9, 19-10 

controllo del contenuto 6-11 

controllo delle 
immagini 10-24 

graficie 10-22-10-24 
Clipbrd, unit 6-9, 10-22 
clock, funzione A-12 
CloneCursor, metodo 27-16 
Close, metodo 

componenti 
connessione 21-4 

connessioni al 
database 24-20 

dataset 22-4 

sessioni 24-19 
CloseDatabase, metodo 24-20 
CloseDataSets, metodo 21-13 
closure 48-2,48-8 

closure, parola chiave 13-25 

CLSID 38-6,38-17,40-5 

file package di licenza 43-8 
CLX 

costruzione di oggetti 14-13 
definizione 3-1 
eVCL 14-5-14-8 
eventi di sistema 51-13 - 
51-16 

notifiche di sistema 51-11 - 
51-16 

segnali 51-11-51-12 

unit 14-10-14-12 
CLX applicazioni 

distribuzione 17-6 
CLX, applicazioni 

applicazioni database 14-21 
- 14-29 

applicazioni Internet 14-30 

creazione 14-1 - 14-2 

panoramica 14-1 

porting in Linux 14-2 - 14-21 
clx60.bpl 17-6 
CM_EXIT, messaggio 56-13 
CMExit, metodo 56-13 
CoClass 
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aggiornamento 39-15 
assegnazione dei nomi 41-3, 
41-5 

controlli ActiveX 43-5 
creazione 38-6, 39-14, 40-6, 

40-13 - 40-14 
dichiarazioni 40-5 
Type Library editor 39-10, 

39- 16 - 39-17 

wrapper di componenti 40-1, 

40- 3 

limiti 40-2 
CoClasses 38-6 

CLSID 38-6 

wrapper di componenti 
_OCX, unit 40-2 
Code editor 2-4 

gestori di evento e 5-4 

panoramica 2-4 

visualizzazione 52-18 
Code Insight 

modelli 7-3 
codice 49-4 

modelli 7-3 

porting in Linux 14-17 - 
14-21 
codice sorgente 

apertura di librerie 10-16 
editing 2-2 
riutilizzo 
visualizzazione 
gestori di evento 
specifici 5-4 
COInit,flag 41-9 
ColCount, proprieta 19-31 
collaudo dei server, Web 

Application Debugger 34-9 
collazione, sequenza A-2 
collegamenti ai dati 56-5 - 56-7 

inizializzazione 56-7 
collegamento statico 

COM 38-18 
colonne 9-17 

cancellazione 19-18 
griglie decisionali 20-12 
inclusione in tabelle 

HTML 33-20 
persistenti 19-17, 19-19 
cancellazione 19-21 
creazione 19-19-19-24 
inserimento 19-20 
riordinamento 19-21 
proprieta 19-19,19-22- 
19-23 

reimpostazione 19-24 



stato predefinito 19-17, 19-24 
colonne dinamiche 19-17 

proprieta 19-18 
colonne persistenti 19-17, 19-19 

cancellazione 19-18, 19-21 

creazione 19-19 - 19-24 

inserimento 19-20 

riordinamento 19-21 
Color, proprieta 9-4, 9-20 

griglie dati 19-22 

griglie decisionali 20-13 

intestazioni di colonna 19-23 

penne 10-6 

pennelli 10-8,10-9 
ColorChanged, metodo 51-14 
colori 

internazionalizzazione 

e 16-10 
penne 10-6 
colori, griglie di 10-6 
Cols, proprieta 9-18 
Columns editor 
cancellazione di 
colonne 19-21 
creazione di colonne 

persistenti 19-19 
riordinamento delle 
colonne 19-21 
Columns, proprieta 9-11, 19-20 
griglie 19-17 
gruppi di pulsanti di 
opzione 9-14 
ColWidths, proprieta 6-15, 9-18 
COM 7-20 

aggregazione 38-9 - 38-10 
applicazioni 38-3 - 38-10, 
38-20 
distribuite 7-20 
binding anticipato 38-18 
client 38-3, 38-10, 39-14, 40-1 

- 40-18 
contenitori 38-10,40-1 
controller 38-10,40-1 
CORBAe 31-1 
definizione 38-1 - 38-2 
estensioni 38-2, 38-10 - 38-13 
panoramica 38-1 - 38-25 
proxy 38-7,38-8 
specifiche 38-1 
stub 38-8 

wizard 38-20 - 38-25, 41-1 
COM+ 7-20,29-7,38-11,38-15, 
44-1 

Vedi anche oggetti 
transazionali 



applicazioni 44-7, 44-29 
Component Manager 44-30 
condivisione di oggetti 44-10 
configurazione di 

attivita 44-21 - 44-22 
eventi 40-16 - 40-17, 44-22 - 

44-26 
MTS e 44-2 

oggetti evento 44-24 - 44-25 
oggetti subscriber di 

eventi 44-25 
oggetti transazionali 38-15 - 

38-16 

puntatori di interfaccia 38-5 
server in-process 38-7 
sincronizzazione delle 

chiamate 44-21-44-22 
transazioni 29-18 
COM, distribuiti 38-7, 38-8 
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combinazione delle 

modifiche 27-36 
commutazione di 

indici 27-10 
con dataset sorgente 

interno 27-23 
con dataset 

unidirezionali 26-11 
condivisione di dati 27-16 
connecting to other 

dataset 27-26-27-34 
connessione ad altri 

dataset 18-10-18-15 
copia di dati 27-15 - 27-16 
creazione di tabelle 27-35 - 

27-36 
distribuzione 17-7 
editing 27-5 

filtraggio dei record 27-2 - 
27-5 
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fornitura di query 27-34 - 

27-35 
indici 27-8-27-11 

aggiunta 27-9 
limitazione dei record 27-31 
parametri 27-29-27-31 
provider e 27-26-27-34 
raggruppamento di 
dati 27-10-27-11 
ricerche basate su 

indice 22-29 
risoluzione degli errori di 

aggiornamento 27-22 
risoluzione errori di 
aggiornamento 27-25 - 
27-26 
salvataggio delle 
modifiche 27-7 
salvataggio di file 27-37 
specifica dei provider 27-27 

- 27-28 
spostamenti nei 27-2 
tipi 27-19-27-20 
vincoli 27-7 - 27-8, 27-32 - 
27-33 
disattivazione 27-32 
dataset decisionale 20-5 - 20-7 
dataset di destinazione, 

definizione 24-50 
dataset non indicizzati 22-20 
dataset sorgente, 

definizione 24-50 
dataset unidirezionali 26-1 - 
26-20 

collegamento 26-6 - 26-8 
connessione ai server 26-2 
esecuzione di comandi 26-9 

-26-11 
limitazioni 26-1 
modifica dei dati 26-11 
prelievo dei metadati 26-13 - 

26-18 

prelievo di dati 26-8 - 26-9 

preparazione 26-9 

tipi 26-2 
dataset, campi 

persistenti 22-39 

visualizzazione 19-26 
dataset, produttori di 
pagine 33-19 

conversione dei valori di 
campo 33-19 
DataSet, proprieta 

grigliedati 19-18 

provider 28-2 



dataset, provider 18-12 
DataSetCount, proprieta 21-13 
DataSetField, proprieta 22-39 
DataSets, proprieta 21-13 
DataSnap, pagina (Component 

palette) 5-8, 29-2, 29-5, 29-6 
DataSource, proprieta 

caselle di riepilogo e 
combinate di 
consultazione 19-13 

controlli ActiveX 40-9 

controlli data-aware 56-6 

database navigator 19-34 

grigliedati 19-18 

query 22-49 
datastore 25-2 
DataType, proprieta 

parametri 22-47,22-48, 

22- 54, 22-55 

date 

componenti calendario 9-13 

impostazione A-7 

inserimento 9-13 

internazionalizzazione 16-10 
DATE , macro 

disponibilita A-7 
DateTimePicker, 

componente 9-13 
dati 

a sola visualizzazione 19-8 
accesso 56-1 
analisi 18-16,20-2 
diagrammazione 18-16 
formati, 

internazionalizzazione 16- 

10 

inserimento 22-19 
modifica 22-17-22-23 
report 18-17 
sincronizzazione delle 

schede 19-4 
stampa 18-17 
valori predefiniti 19-11, 

23- 22 

visualizzazione 23-18, 23-19 
disattivazione 

ritracciamento 19-6 
nelle griglie 19-17, 19-30 
valori correnti 19-9 
dati immessi, convalida 23-17 
dati, filtri 

campi vuoti 22-15 
definizione 22-14-22-16 
operatori 22-15 
uso di segnalibri 25-11 



dati, moduli 
Web 34-2 
dati, vincoli Vedi vincoli 
Day, proprieta 55-6 
DB/2, driver 

distribuzione 17-10 
dBASE, tabelle 24-5 
assegnazione nuovo 

nome 24-8 
DatabaseName 24-3 
indici 24-7 
protezione con 

password 24-22-24-24 
transazioni locali 24-33 
DBChart, componente 18-16 
DBCheckBox, componente 19-2, 

19-14 - 19-15 
DBComboBox, 

componente 19-11 - 19-12 
DBConnection, proprieta 27-18 
DBCtrlGrid, componente 19-3, 
19-30 - 19-31 
proprieta 19-31 
DBEdit, componente 19-2, 19-9 
dbExpress 17-7, 18-2, 26-1 - 26-2 
applicazioni 
multipiattaforma 14-21 - 
14-28 

componenti 26-1-26-20 

debug 26-18-26-20 

distribuzione 26-1 

driver 26-3-26-4 

metadati 26-12-26-18 
dbExpress, applicazioni 17-11 
dbExpress, pagina (Component 

palette) 5-8,18-2,26-2 
dbGo 25-1 

DBGrid, componente 19-2, 

19-16 - 19-30 
eventi 19-29 
proprieta 19-22 
DBGridColumns, 

componente 19-17 
DBImage, componente 19-2, 

19-10 - 19-11 
DblClick, metodo 51-14 
DBListBox, componente 19-2, 

19-11 - 19-12 
DBLogDlg, unit 21-4 
DBLookupComboBox, 

componente 19-12 - 19-14 
DBLookupListBox, 

componente 19-2, 19-12 - 

19-14 
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DBMemo, componente 19-2, 

19-9 - 19-10 
DBMS 29-1 
DBNavigator, 

componente 19-2, 19-31 - 

19-34 
DBRadioGroup, 

componente 19-2, 19-15 
DBRichEdit, componente 19-3, 

19- 10 

DBSession, proprieta 24-3, 24-4 
DBText, componente 19-2, 19-8 
-19-9 

dbxconnections.ini 26-4, 26-5 - 
26-6 

dbxdrivers.ini 26-3 - 26-4 
DCOM 38-7, 38-8 
applicazioni 

InternetExpress 29-35 
applicazioni multi-tier 29-10 
connessione all'application 

server 27-28, 29-24 
distribuzione di 
applicazioni 7-20 
DCOM connessioni 29-10, 29-24 
DCOMCnfg.exe 29-36 
.dcr,file 52-4 

bitmap 45-15 
DDL 21-11, 22-45, 22-51, 24-9, 

26-11 
debug 

Active Server Objects 42-8 - 

42-9 
applicazioni 

dbExpress 26-18-26-20 
applicazioni di servizio 7-9 
applicazioni Web server 32-9 

- 32-12, 33-2 
codice 2-5 

controlli ActiveX 43-17 
CORBA 31-17-31-19 
oggetti COM 41-9, 41-18 
oggetti transazionali 44-28 - 

44-29 
Web server, 

applicazioni 34-9 
wizard 58-11-58-12 
debugger integrato 2-5 
decimale, punti A-7 
Decision Cube Editor 20-7 - 

20- 9 

Cube Capacity 20-20 
Dimension Settings 20-8 
Memory Control 20-8 



Decision Cube, pagina 
(Component palette) 18-16, 
20-1 

Decision Query editor 20-6 

declspec 13-3 

declspec(delphirtti) 36-2 

declspec, parola chiave 7-12, 

13-29 
DECnet, protocollo 

(Digital) 37-1 
default 

parola chiave 47-8 
Default, casella di controllo 7-3 
Default, proprieta 

elementi di azione 33-7 
DEFAULT_ORDER, indice 27-8 
DefaultColWidth, 

proprieta 9-18 
DefaultDatabase, proprieta 25-4 
DefaultDrawing, 

proprieta 6-13, 19-29 
DefaultExpression, 

proprieta 23-22,27-8 
DefaultHandler, metodo 51-4 
DefaultPage, proprieta 34-42 
DefaultRowHeight, 

proprieta 9-18 
definizioni di indici 

copia 22-41 
definizioni di tipo 

Type Library editor 39-10 - 
39-11 
delega 48-1 

Delete Table, comando 22-42 
Delete Templates, comando 

(Menu designer) 8-40, 8-42 
Delete Templates, finestra di 

dialogo 8-42 
Delete, comando (Menu 

designer) 8-40 
DELETE, istruzioni 24-42, 

24-45, 28-10 
Delete, metodo 22-20 

elenchi di stringhe 4-20, 4-21 
DeleteAlias, metodo 24-27 
DeleteFile, funzione 4-7 
DeleteFontResource, 

funzione 17-15 
Deletelndex, metodo 27-10 
DeleteRecords, metodo 22-43 
DeleteSQL, proprieta 24-42 
DeleteTable, metodo 22-42 
delphiclass, argomento 13-29 
Delphilnterface, classe 13-3, 

13-4, 13-21, 58-8 



delphireturn, argomento 13-29, 
13-30 

Delta, proprieta 27-5, 27-21 
DEPLOY 17-16 
DEPLOY, documento 17-9, 
17-16 

dereferenziati, puntatori 13-7 
derivazione di classe per 
controlli Windows 45-4 
dettagli annidati 22-38 - 22-39 
dettaglio, tabelle annidate 29-20 
dettaglio, tabelle, 

annidate 23-27-23-28 
device, interattivi A-2 
DeviceType, proprieta 10-33 
.dfm,file 14-2,16-10,47-11 

generazione 16-13 
Dialogs, pagina (Component 

palette) 5-8 
dichiaratori 

annidamento A-6 
numero di A-6 
dichiarazioni 

classi 46-11, 54-6 
interfacce 13-2 
private 46-5 
protected 46-7 
public 46-7 
published 46-8 
gestori di evento 48-5, 48-8, 
55-13 

gestori di messaggi 51-5, 

51-6, 51-8 
metodi 10-16, 46-10, 49-4 

public 49-3 
proprieta 47-3, 47-3 - 47-7, 
47-8, 47-13, 48-8, 54-4 
tipi definiti 
dall'utente 54-4 
tipi dei nuovi 
componenti 46-3 
dichiarazioni di tipo 
proprieta 54-4 
tipi enumerati 10-13, 10-14 
DII 31-15,31-16 

Interface Repository 31-13 
DimensionMap, proprieta 20-6, 
20-7 

Dimensions, proprieta 20-13 
Direction, proprieta 

parametri 22-48,22-55 
directory 

e Linux 14-16 

file include A-7 
directory, servizio 31-3 
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direttive 

#ifdef 14-18 
#ifndef 14-19 
$LIBPREFIX, 

compilatore 7-11 
$LIBSUFFIX, 

compilatore 7-11 
SUBVERSION, 

compilatore 7-11 
compilazione 

condizionale 14-18 
Linux 14-19 
protected 48-5 
published 47-3, 57-4 
direttive al compilatore 
librerie 7-11 
package 15-12 
diritti di accesso 

WebSnap 34-31 - 34-33 
DirtyRead 21-10 
DisableCommit, metodo 44-14 
DisableConstraints, 

metodo 27-32 
DisableControls, metodo 19-6 
Disabledlmages, proprieta 8-50 
dischi CDaudio 10-34 
DisconnectEvents, 

metodo 40-16 
dispatch actions 34-10 
dispatch, interfacce 41-13, 41-14 
-41-15 
chiamata a metodi 40-14 - 
40-15 

compatibilita dei tipi 41-16 
identificatori 41-14 
librerie di tipi 39-10 
Dispatch, metodo 51-4, 51-5 
dispatcher 33-2, 33-4 - 33-6, 
34-37, 34-42 
applicazioni basate su 

DLL 33-3 
gestione delle richieste 33-9 
oggetti auto-dispatch 33-5 
selezione di elementi di 
azione 33-6, 33-7 
dispID 38-18, 40-15, 41-14 

collegamento a 41-15 
dispinterface 41-13, 41-14 - 
41-15 

binding dinamico 39-10 
librerie di tipi 39-10 
DisplayFormat, proprieta 19-29, 

23-12, 23-16 
DisplayLabel, proprieta 19-19, 
23-12 



DisplayWidth, proprieta 19-18, 
23-12 

dispositivi di supporto 10-33 
distribuite, applicazioni 

database 7-17 

MTSeCOM+ 7-20 
distribuiti, oggetti 

CORBA Vedere CORBA, 
oggetti 
distributor! di risorse 44-6 

ADO 44-6 

BDE 44-6 
distribuzione 

applicazioni 17-1 

applicazioni CLX 17-6 

applicazioni database 17-6 

applicazioni generiche 17-1 

applicazioni MIDAS 17-10 

applicazioni Web 17-10 

Borland Database 
Engine 17-9 

controlli ActiveX 17-5 

dbExpress 26-1 

estensioni dell'IDE 58-7, 
58-23 - 58-25 

file DLL 17-6 

file package 17-3 

SQL Links 17-9 
distribuzione di applicazioni 

package 15-14 
distruttori 12-6, 49-3, 56-7 

implicazioni nella 
VCL 13-13, 13-14 - 13-15 

oggetti posseduti e 54-6, 54-7 
divisione 

segno del resto A-5 
Dizionario dati 23-14 - 23-15 
DLL 7-13 

creazione 7-10, 7-12 

distribuzione 17-10 

incorporazione in 
HTML 33-15 

installazione 17-6 

internazionalizzazione 16-11 
, 16-13 

link 7-15 

Linux Vedere .so, file 
MTS 44-2 

package 15-1, 15-2, 15-12 

server COM 38-7 

modelli di threading 41-7 

server HTTP 32-6, 32-7 
dllexport 7-12,7-13 
DllGetClassObject 44-3 
dllimport 7-11 



DllRegisterServer 44-3 
DML 21-11,22-45,22-51,24-9 
.dmt,file 8-41,8-42 
Document Literal, stile 36-1 
DocumentElement, 

proprieta 35-4 
DoExit, metodo 56-13 
DOM 35-2,35-2-35-3 

implementazioni 35-2 
utilizzo 35-4 
dominio, errori A-8 
DoMouseWheel, metodo 51-14 
doppio clic 

componenti 52-16 

risposta a 52-18 - 52-19 
Down, proprieta 9-8 

pulsanti di scelta rapida 8-48 
.dpi, file 15-2 
drag-and-dock 6-4-6-7 
drag-and-drop 6-1 - 6-4 

DLL 6-4 

eventi 54-3 

ottenimento di informazioni 
distato 6-4 

personalizzazione 6-4 

puntatore del mouse 6-4 
DragMode, proprieta 6-1 

griglie 19-21 
DragOver, metodo 51-14 
Draw, metodo 10-4, 50-3, 50-7 
DrawShape 10-16 
drill-down, schede 19-16 
drintf, unit 24-56 
DriverName, proprieta 24-14, 
26-3 

DropConnections, 

metodo 24-14,24-21 
DropDownCount, 

proprieta 9-12, 19-12 
DropDownMenu, 

proprieta 8-52 
DropDownRows, proprieta 
caselle combinate di 

consultazione 19-14 
griglie dati 19-22, 19-23 
durability 

distributor! di risorse 44-6 
transazioni 18-5,44-11 
dynamic array, tipi 36-4 
dynamic invocation interface 

Vedere DII 
dynamic, argomento 13-30 

E 

EBX, registro 14-9, 14-21 
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eccezioni 49-2, 51-3 

costruttori 13-14 

definizione 12-1 

formatobit 12-12 

generazione 4-2 

Linux 14-15 

rigenerazione 4-2 

threads 11-7 
eccezioni non gestite 12-6 
eccezioni strutturate 12-7 
eccezioni, basate su C, 

gestione 12-7 
eccezioni, gestione 

funzioni helper 12-7 
Edit,metodo 22-18,52-10,52-11 
EditFormat, proprieta 19-29, 

23-12, 23-16 
editing del codice 2-2, 2-4 
EditKey, metodo 22-29, 22-31 
EditMask, proprieta 23-15 

campi 23-12 
editor 

API Tools 58-3, 58-13 - 58-14 
editor di componenti 52-16 - 
52-20 
predefiniti 52-16 
registrazione 52-19 
editor di proprieta 5-3, 47-2, 
52-7-52-13 
attributi 52-11 
come classi derivate 52-8 
finestre di dialogo 

come 52-10 
registrazione 52-12 - 52-13 
EditRangeEnd, metodo 22-35, 
22-36 

EditRangeStart, metodo 22-35 
effetto elastico, esempio 10-24 - 

10-30 
elaborazione di dati 

distribuiti 29-2 
elaborazione multiprocessore 

thread 11-1 
elementi di azione 33-3, 33-4, 
33-6 - 33-9 
aggiunta 33-5 
attivazione e 

disattivazione 33-7 
avvertenze in modifica 33-3 
concatenamento 33-9 
gestori di evento 33-4 
predefiniti 33-5, 33-7 
produttori di pagine e 33-16 
risposta a richieste 33-8 
selezione 33-6, 33-7 



elementi grafici 

aggiunta a HTML 33-15 
associazione a stringhe 4-21 
autonomi 50-3 
cancellazione 10-23 
caricamento 10-20, 50-4, 50-5 
complessi 50-6 
contenitori 50-4 
copia 10-23 

disegno di linee 10-6, 10-10 - 
10-11, 10-29 - 10-30 
cambio dello spessore 
della penna 10-6 
disegno e tracciamento 10-4 
esempio di effetto 

elastico 10-24-10-30 
formati dei file 10-3 
funzioni, chiamata 50-1 
in frame 8-16 
incollaggio 10-24 
internazionalizzazione 16-10 
metodi 50-3,50-4 

copia di immagini 50-7 
tavolozze 50-5 
panoramica sulla 
programmazione 10-1 - 
10-4 

registrazione 50-4 
ridimensionamento 10-21, 

19-10, 50-7 
ridisegno delle 

immagini 50-7 
salvataggio 10-21,50-4 
sostituzione 10-21 
strumenti di disegno 50-7, 
54-6 
cambio 54-8 
visualizzazione 9-19 
elementi grafici indipendenti 

dal dispositivo 50-1 
elementi Web 29-39 

proprieta 29-40-29-41 
elenchi 

uso in thread 11-5 
elenchi a discesa 19-23 
elenchi di azioni 5-5, 8-19, 8-21, 

8-25 - 8-53 
elenchi di file 

rilascio di elementi 6-3 
trascinamento di 
elementi 6-2, 6-3 
elenchi di ricerca (sistemi di 

Guida) 52-5 
elenchi di stringhe 4-16 - 4-21 
a breve termine 4-17 



a lungo periodo 4-18 

aggiunta a 4-19 

cancellazione di 
stringhe 4-20 

caricamento da file 4-16 

controlli owner-draw 6-13 - 
6-14 

copia 4-20 

creazione 4-17-4-18 

iterazione tra 4-19 

oggetti associati 4-20 - 4-21 

ordinamento 4-20 

posizione in 4-19 

ricerca di stringhe 4-19 

salvataggio su file 4-16 

sottostringhe 4-19 

spostamento di stringhe 4-20 
Ellipse, metodo 10-5, 10-12, 50-3 
ellissi 

disegno 10-11,54-10 
Embed, marcatore HTML 

(<EMBED>) 33-15 
EmptyDataSet, metodo 22-43, 
27-29 

EmptyTable, metodo 22-43 
EnableCommit, metodo 44-14 
EnableConstraints, 

metodo 27-32 
EnableControls, metodo 19-6 
Enabled, proprieta 

controlli data-aware 19-7 

elementi di azione 33-7 

menu 6-10,8-44 

sorgenti dati 19-4, 19-6 
EnabledChanged, metodo 51-15 
end user adapter 34-10, 34-27 
ENDJVIESSAGEJVIAP, 

macro 51-4,51-8 
EndRead, metodo 11-9 
EndWrite, metodo 11-9 
enumerati, tipi 

Web Services 36-6 
enumerazioni A-6 
EOF, contrassegno 4-4 
Eof, proprieta 22-6, 22-7, 22-8 
era, clock, funzione A-12 
EReadError 4-2 
eredita 

limitazioni 13-2 

multipla 13-2 
eredita da classi 3-4 - 3-5 
ereditate 

proprieta 54-3, 55-3 
pubblicazione 47-3 
ereditati 
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eventi 48-5 

metodi 48-6 
ERemotableException 36-15 
errori 

dominio A-8 

socket 37-8 

underflow range A-8 
errori di aggiornamento 

messaggi di risposta 29-38 

risoluzione 27-22, 27-25 - 
27-26, 28-9, 28-12 
eseguibili, file 

in Linux 14-15 
esercizio 

WebSnap 34-12-34-24 
estensioni del linguaggio 13-29 
estensioni delle parole 

chiave 13-24 
estesi, set di caratteri A-2 
etichette 9-4, 16-10, 19-2, 45-4 

colonne 19-19 
Euro, conversioni 4-32, 4-35 
EventFilter, metodo 

eventi di sistema 51-15 
eventi 5-3 - 5-6, 45-7, 48-1 - 
48-10 

a livello di applicazione 8-2 
accesso 48-5 
ADO, connessioni 25-7 - 
25-9 

assegnazione dei nomi 48-8 

associazione a gestori 5-5 

attesadi 11-10 

attivazione 43-11 

broker XML 29-38 

COM 41-11, 41-12 

COM+ 40-16 - 40-17, 44-22 - 

44-26 
condivisi 5-5 

controller Automation 40-12, 

40-15 - 40-17 
controlli ActiveX 43-11 - 

43-12 
controlli data-aware 
attivazione 19-7 
controlli grafici 50-7 
definizione di nuovi 48-6 - 

48-10 
ereditati 48-5 

gestione dei messaggi 51-4, 
51-7 

griglie dati 19-29 - 19-30 
implementazione 48-2, 48-4 
interfacce 41-11 
login 21-5 



mouse 10-25-10-27 

verificadi 10-27 
oggetti Automation 41-5 
oggetti campo 23-16 - 23-17 
oggetti COM 41-4, 41-11 - 

41-12 
predefiniti 5-4 
preparazione della 

guida 52-4 
risposta a 48-6, 48-7, 48-8, 

48-9, 56-8 
segnalazione 11-10 
sistema 3-3 

sorgentidati 19-4-19-5 

standard 48-4 

timeout 11-11 

tipi 3-3 

utente 3-3 

VCL, wrapper di 
componenti 40-3 
eventi clic 10-26, 48-1, 48-8 
eventi del mouse 54-3 
eventi di notifica 48-7 
eventi di sistema 

personalizzazione 51-15 
eventi di tastiera 

internazionalizzazione 16-9 
EWriteError 4-2 

except, parola chiave 12-7, 

12-8 
Exception 

definizione 3-5 

except, parola chiave 12-11 

Exception, classe 12-17 
Exclusive, proprieta 24-6 
ExecProc, metodo 22-56, 26-11 
ExecSQL, metodo 22-50, 22-51, 
26-10 

oggetti update 24-48 
Execute, metodo 

comandiADO 25-18-25-19, 
25-20 

componenti 
connessione 21-11 

dataset client 27-30, 28-3 

finestr di dialogo 8-17, 57-5 

provider 28-3 

TBatchMove 24-54 

thread 11-4 
ExecuteOptions, 
proprieta 25-11 
ExecuteTarget, metodo 8-31 
EXISTINGARRAY, 

macro 13-18,13-20 
exit, funziones A-ll 



Expandable, proprieta 19-26 
Expanded, proprieta 

colonne 19-25,19-26 

griglie dati 19-22 
Expression, proprieta 27-13 
ExprText, proprieta 23-11 

F 

fabbriche di classi 38-6 
facoltativi, parametri 27-16 
factory 34-5 

FastNet, pagina (Component 

palette) 5-8 
Fetch Params, comando 27-29 
FetchAll, metodo 14-29, 24-34 
FetchBlobs, metodo 27-29, 28-4 
FetchDetails, metodo 27-29, 

28-4 

fetch-on-demand 27-29 
FetchOnDemand, 

proprieta 27-29 
FetchParams, metodo 27-29, 

28-3 

fgetpos, funzione A-10 
field datalink, classe 56-11 
Field Link designer 22-37 
FieldAddress, metodo 13-23 
FieldByName, metodo 22-33, 
23-21 

FieldCount, proprieta 

campi persistenti 19-19 
FieldDefs, proprieta 22-41 
FieldKind, proprieta 23-12 
FieldName, proprieta 23-6, 
23-12, 29-40 
campi persistenti 19-19 
griglie dati 19-22, 19-23 
griglie decisionali 20-13 
Fields editor 7-24,23-3 

applicazione degli attributi 

di campo 23-15 
barra del titolo 23-4 
cancellazione di campi 

persistenti 23-11 
creazione di campi 
persistenti 23-4 - 23-5, 23-5 
- 23-11 
definizione dei set di 

attributi 23-14 
liste di campi 23-5 
pulsanti di navigazione 23-4 
rimozione del set di 

attributi 23-15 
riordinamento delle 
colonne 19-21 
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Fields, proprieta 23-21 
FieldValues, proprieta 23-21 
figure 9-20, 10-11 - 10-12, 10-14 
disegno 10-11,10-14 
riempimento 10-8, 10-9 
riempimento con 

bitmap 10-10 
tracciamento di 
contorni 10-6 
figure geometriche 

disegno 54-10 
file 4-4-4-13 
aggiunta A-9 
apertura 

abort, funzione A-ll 
ripetuta A-9 
buffer A-9 
cambio del nome 4-9 
cancellazione 4-7 
con lunghezza zero A-9 
copia 4-10 
dimensioni 4-4 
grafici 10-20 - 10-22, 50-4 
handle 4-5,4-7 
invio attraverso il Web 33-13 
modalita 4-7 
operazioni con 4-4 - 4-13 
posizione 4-4 
ricerca 4-4,4-8 
risorse 8-45 
routine 

API di Windows 4-5 
della libreria runtime 4-7 
routine di data-ora 4-9 
routine di data-ora 4-9 
temporanei A-ll 
trattamento 4-7-4-10 
troncamento durante la 
scrittura A-9 
file bitmap per la palette 52-4 
file di licenza dei package 43-8 
file di trasformazione 30-1 - 
30-6 

nodi definiti dall'utente 30-5, 

30-7-30-8 
TXMLTransform 30-7 
TXMLTransformClient 30-9 
TXMLTransformProvider 30 

-8 

file eseguibili 

internazionalizzazione 16-11 
, 16-13 

server COM 38-7 
fileindice 24-7 



file indice non di 

produzione 24-7 
file scheda 3-8, 16-13 
file sorgente 

modifica 2-2 
file sorgenti A-7 

condivisione (Linux) 14-14 

package 15-2 
FileAge, funzione 4-9 
FileExists, funzione 4-8 
FileGetDate, funzione 4-9 
FileName, proprieta 

dataset client 18-10, 27-36, 
27-37 

files 

scheda 14-2 
FileSetDate, funzione 4-9 
FillRect, metodo 10-5, 50-3 
Filter, proprieta 22-14, 22-14 - 
22-15 

Filtered, proprieta 22-13 
FilterGroup, proprieta 25-12, 

25-14 
FilterOnBookmarks, 

metodo 25-11 
FilterOptions, proprieta 22-16 
filtri 22-13 - 22-16 
attivazione/ 

disattivazione 22-13 
campi vuoti 22-15 
confronto di stringhe 22-16 
dataset client 27-3 - 27-5 

conparametri 27-31 
definizione 22-14 - 22-16 
eintervalli 22-32 
gestione delle eccezioni 12-9 
impostazione in 

esecuzione 22-16 
operatori 22-15 
opzioni per campi di 

testo 22-16 
query e 22-13 
sensibilita maiuscole/ 

minuscole 22-16 
uso di segnalibri 25-11 
filtri dati 22-13 - 22-16 
attivazione/ 

disattivazione 22-13 
impostazione in 

esecuzione 22-16 
query e 22-13 
filtri sui dati 

dataset client 27-3 - 27-5 
conparametri 27-31 



finally, parola chiave 12-7, 

12-13 

FindClose, procedura 4-8 
FindDatabase, metodo 24-21 
FindFirst, funzione 4-8 
FindFirst, metodo 22-17 
FindKey, metodo 22-29, 22-30 

EditKeye 22-31 
FindLast, metodo 22-17 
FindNearest, metodo 22-29, 
22-30 

FindNext, funzione 4-8 
FindNext, metodo 22-17 
FindPrior, metodo 22-17 
FindResourceHInstance, 

funzione 16-12 
FindSession, metodo 24-30 
finestra 

classe 45-4 

controlli 45-4 

gestione dei messaggi 55-4 

handle 45-4,45-6 

procedure 51-3 
finestre 

ridimensionamento 9-7 
finestre di dialogo 57-1 - 57-7 

comuni 8-16 

comuni di Windows 57-2 
creazione 57-2 
esecuzione 57-5 
creazione 57-1 
DLL, esempio di 7-13 
editor di proprieta 

come 52-10 
impostazione dello stato 

iniziale 57-2 
internazionalizzazione 16-9, 

16-10 
multipagina 9-16 
finestre di dialogo comuni 8-16, 
57-1, 57-2 
creazione 57-2 
esecuzione 57-5 
Fire 43-11 

FireOnChanged 43-13 
FireOnRequestEdit 43-13 
First Impression 17-5 
First, metodo 22-6 
FixedColor, proprieta 9-18 
FixedCols, proprieta 9-18 
FixedOrder, proprieta 8-52, 9-10 
FixedRows, proprieta 9-18 
FixedSize, proprieta 9-10 
flag 56-4 

FlipChildren, metodo 16-7 
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FloodFill, metodo 10-5, 50-3 
fly-by help 9-17 
fmod, funzione A-8 
FocusControl, metodo 23-17 
FocusControl, proprieta 9-4 
foglidi stile 29-41 
font 

altezza del 10-5 
Font, proprieta 9-3, 9-4, 10-4, 
50-3 

controlli memo data- 
aware 19-9 

grigliedati 19-22 

intestazioni di colonna 19-23 
FontChanged, metodo 51-15 
Footer, proprieta 33-21 
FOREIGN KEY, vincolo 28-14 
Format, proprieta 20-13 
formati A- 12 

formati dati, predefiniti 23-16 
formattazione dei dati 

applicazioni 
internazionali 16-10 
Forms unit 

applicazioni Web 33-3 
Formula One 17-5 
fornitura 28-1, 29-4 
Found, proprieta 22-17 
FoxPro, tabelle 

transazioni locali 24-33 
frame 8-12,8-14-8-16 

condivisione e 
distribuzione 8-16 

e modelli di 
componenti 8-15, 8-16 

grafici 8-16 

risorse 8-16 
FrameRect, metodo 10-5 
FReadOnly 56-9 
free, modello di threading 41-7 
-41-8 

FreeBookmark, metodo 22-10 
FromCommon 4-32 
ftell, funzione A-10 
funzionalita 

non portabili di 
Windows 14-8 
funzioni 45-7 

API di Windows 45-4, 50-1 

argomenti 13-8 

assegnazione dei nomi 49-2 

C++ e Object Pascal 13-24 

grafici 50-1 

impostazione di 
proprieta 52-12 



lettura delle proprieta 47-7, 
52-9, 52-11 

matematiche A-8 

tipo restituito 49-2 

virtuali 13-12 
funzioni esportate 7-12, 7-13 
funzioni importate 7-11 
funzioni membro 3-3 

impostazione di 
proprieta 47-7 
fuoco 45-4 

campi 23-17 

spostamento 9-6 
fuoco di input 45-4 

campi 23-17 
fuoco in ingresso 45-4 

G 

Generate event support 

code 41-11 
gerarchia (classi) 46-4 
gestione dei messaggi 51-4 - 

51-6 

ridefinizione 51-4 
gestione della memoria 

componenti decisionali 20-8, 

20-20 
schede 8-5 
gestione delle eccezioni 12-1 - 
12-19 
bloccotry 12-2 
costruttori e distruttori 12-6 
eccezioni strutturate 12-7 
esempio 12-11 
sintassi 12-7 
filtri 12-9 

istruzione catch 12-3 
istruzione throw 12-2 
opzioni del 

compilatore 12-15 
puntatori safe 12-5 
sintassi C++ 12-2 
specifica dell'eccezione 12-4 
VCL 12-15 
gestione delle eccezioni 

Win32 12-7 
gestori di evento 5-3 - 5-6, 45-7, 
48-2, 48-8, 56-8 
associazione a eventi 5-5 
cancellazione 5-6 
condivisi 5-5 - 5-6, 10-16 
definizione 5-3 
dichiarazioni 48-5, 48-8, 
55-13 

disegno di linee 10-27 



individuazione 5-4 
menu 5-6, 6-11 
metodi 48-5 

ridefinizione 48-6 
modelli di menu 8-43 
parametri 48-8,48-9 

eventi di notifica 48-7 
parametro Sender 5-5 
passaggio di parametri per 

riferimento 48-9 
predefiniti, 

ridefinizione 48-9 
risposta ai clic del 

pulsante 10-14 
scrittura 5-4 
tipi 48-3,48-7-48-8 
tipo restituito 48-3 
visualizzazione in Code 

editor 52-18 
vuoti 48-9 
gestori di messaggi 51-1, 51-3 
creazione 51-6 - 51-8 
dichiarazioni 51-5, 51-6, 51-8 
metodi, ridefinizione 51-8 
predefiniti 51-4 
gestori di messaggio 55-5 
GetAliasDriverName, 

metodo 24-27 
GetAliasNames, metodo 24-27 
GetAliasParams, metodo 24-27 
GetAttributes, metodo 52-11 
GetBookmark, metodo 22-10 
GetConfigParams, 

metodo 24-27 
GetData, metodo 

campi 23-18 
GetDatabaseNames, 

metodo 24-27 
GetDriverNames, metodo 24-27 
GetDriverParams, 

metodo 24-27 
getenv, funzione A- 11 
GetExceptionCode, 

funzione 12-7 
GetExceptionlnformation, 

funzione 12-7, 12-9 
GetFieldByName, metodo 33-9 
GetFieldNames, metodo 21-14, 
24-28 

GetFloatValue, metodo 52-9 
GetGroupState, metodo 27-11 
GetHandle 7-31 
GetHelpFile 7-31 
GetHelpStrings 7-32 
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GetIDsOfNames,metodo 40-15, 
41-14 

GetlndexNames, metodo 21-15, 
22-28 

Getlnterface, metodo 13-4 
GetMethodValue, metodo 52-9 
GetNextPacket, metodo 14-29, 

24-34, 27-28, 27-29, 28-4 
GetOptionalParam, 

metodo 27-16,28-7 
GetOrdValue, metodo 52-9 
GetPalette, metodo 50-5, 50-6 
GetParams, metodo 28-3 
GetPassword, metodo 24-23 
GetProc Address 7-11 
GetProcedureNames, 

metodo 21-15 
GetProcedureParams, 

metodo 21-15 
GetProperties, metodo 52-11 
GetRecords, metodo 28-4, 28-8 
GetSessionNames, 

metodo 24-30 
GetStoredProcNames, 

metodo 24-27 
GetStrValue, metodo 52-9 
GetTableNames, metodo 21-14, 

24-28 

GetValue, metodo 52-9 
GetVersionEx, funzione 17-16 
GetViewerName 7-30 
GetXML, metodo 30-10 
-Gi, opzione del linker 15-13 
-Gl, opzione del linker 15-13 
Global Offset Table 

(GOT) 14-21 
Glyph, proprieta 8-48, 9-8 
GNU assembler 
Linux 14-18 
GNU make, utilita 

Linux 14-16 
GotoBookmark, metodo 22-10 
GotoCurrent, metodo 22-43 
GotoKey, metodo 22-29, 22-30 
GotoNearest, metodo 22-29, 

22-30 

-Gpd, opzione del linker 15-13 
-Gpr, opzione del linker 15-13 
grafici 45-7, 50-1 - 50-8 

aggiunta di controlli 10-18 

controlli owner-draw 6-12 

disegno di linee 

gestori di evento 10-27 

file 10-20-10-22 

modifica di immagini 10-21 



tipi degli oggetti 10-3 - 10-4 
tracciamento e disegno 10-23 
grafici decisionali 20-13 - 20-19 
comportamenti in 

esecuzione 20-20 
dimensioni 20-14 
modelli 20-17 
opzioni di 

visualizzazione 20-15 
personalizzazione 20-16 - 

20-19 

serie dei dati 20-18 - 20-19 
stati del pivot 20-9, 20-10 
tipi di grafici 20-17 
grafici, metodi 50-6 
Graph Custom 17-5 
Graphic, proprieta 10-19, 10-22 
GridLine Width, proprieta 9-18 
griglie 9-17 - 9-18, 19-3, 55-1, 
55-3, 55-6, 55-13 
aggiunta di righe 22-19 
associate ai dati 19-16, 19-30 
colore 10-6 
disegno 19-28-19-29 
editing dei dati 19-6, 19-28 
inserimento di colonne 19-20 
opzioni di esecuzione 19-26 

- 19-28 
ottenimento di valori 19-19 
personalizzazione 19-18 - 
19-24 

rimozione di colonne 19-18, 

19-21 
riordinamento delle 

colonne 19-21 
ripristino dello stato 

predefinito 19-24 
stato predefinito 19-17 
visualizzazione dei 

dati 19-17, 19-18, 19-30 
griglie dati 19-2, 19-3, 19-16, 
19-16 - 19-30 
disegno 19-28-19-29 
editing dei dati 19-6, 19-28 
eventi 19-29-19-30 
inserimento di colonne 19-20 
opzioni di esecuzione 19-26 

- 19-28 
ottenimento di valori 19-19 
personalizzazione 19-18 - 

19-24 
proprieta 19-31 
rimozione di colonne 19-18, 

19-21 



riordinamento delle 

colonne 19-21 
stato predefinito 19-17 
visualizzazione dei 
dati 19-17,19-18,19-30 
ADT, campi 19-24 
campi array 19-24 
griglie decisionali 20-11 - 20-13 
comportamenti in 
esecuzione 20-19 
dimensioni 

apertura/chiusura 20-11 
drill down 20-12 
riordinamento 20-12 
selezione 20-12 
eventi 20-13 
proprieta 20-12 
stati del pivot 20-9, 20-10, 
20-12 

griglie di disegno 9-18 
griglie tabellari 19-30 
groglie dati 

ripristino dello stato 
predefinito 19-24 
Grouped, proprieta 

pulsanti strumento 8-50 
Group Index, proprieta 9-8 

menu 8-44 

pulsanti di scelta rapida 8-48 
GroupLayout, proprieta 20-10 
Groups, proprieta 20-10 
gruppi di opzioni 9-14 
gruppi di proprieta 

condivise 44-7 
GUI applicazioni 8-1 
GUID 38-4, 39-8, 40-5 
Guida 52-4 

informazioni di tipo 39-9 

sensibile al contesto 9-17 

suggerimenti 9-17 

tool-tip 9-17 
guida in linea 52-4 
guida rapida 19-34 

H 

.h,file 15-2,15-14 
handle 

connessioni socket 37-7 
moduli di risorsa 16-12 
Handle, proprieta 4-7, 37-7, 
45-4, 45-5, 50-3 
contesto del dispositivo 10-2 
HANDLEJVISG, macro 51-2 
HandleException, metodo 51-3 
HandleShared, proprieta 24-17 
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HandlesTarget, metodo 8-31 
HasConstraints, proprieta 23-12 
HasFormat, metodo 6-11, 10-24 
header 

richieste HTTP 32-4 
header del messaggio 

(HTTP) 32-3 
header della richiesta 33-9 
header della risposta 33-13 
header, controlli 9-16 
Header, proprieta 33-21 
Height, proprieta 8-4 

caselle di riepilogo 19-12 
Help Manager 7-28, 7-29 - 7-38 
Help, selettori 7-35, 7-37 
Help, sistemi 7-28 

interfacce 7-29 

registrazione di oggetti 7-34 
Help, visualizzatori 7-28 
HelpContext 7-37 
HelpContext, proprieta 7-36, 
9-17 

helper, oggetti 4-1 
HelpFile property 9-17 
HelpFile, proprieta 7-37 
Helplntfs, unit 7-29 
HelpKeyword 7-37 
Help Keyword, proprieta 7-36 
HelpSystem 7-36 
HelpType 7-36,7-37 
hidesbase, argomento 13-30 
Hint, proprieta 9-17 
Hints, proprieta 19-34 
holder, classi 36-6 
HookEvents, metodo 51-12 
HorzScrollBar 9-5 
host 29-25, 37-4 

indirizzi 37-4 

URL 32-4 
Host, proprieta 

TSocketConnection 29-25 
Hotlmages, proprieta 8-50 
HotKey, proprieta 9-6 
HTML Result, pagina 34-2 
HTML Script, pagina 34-2 
HTML, comandi 33-14 

generazione 33-15 

informazioni di 
database 33-19 
HTML, documenti 32-5 

applicazioni 
InternetExpress 29-33 

ASP e 42-1 

controlli AactiveX 
incorporati 43-1 



database e 33-18 
dataset 33-21 
foglidi stile 29-41 
generati per 

ActiveForms 43-6 
incorporamento di 

tabelle 33-21 
messaggi di risposta 

HTTP 32-6 
modelli 29-39, 29-41 - 29-43, 

33-14 - 33-16 
produttori di pagine 33-14 - 

33-18 

produttori di pagine di 

dataset 33-19 
produttori di tabelle 33-19 - 

33-21 

HTML, modelli 29-41 - 29-43, 
33-14 - 33-18, 34-4 
predefiniti 29-39, 29-41 
HTML,schede 29-40 
HTML, tabelle 33-15, 33-21 
creazione 33-19 - 33-21 
impostazione delle 

proprieta 33-20 
titoli 33-21 
HTMLDoc, proprieta 29-39, 
33-15 

HTMLFile, proprieta 33-15 
HTML-transparente, marcatori 

predefiniti 29-42 
HTML-trasparente, marcatori 

conversione 33-14, 33-16 

parametri 33-14 

predefiniti 33-15 

sintassi 33-14 
HTTP 32-3 

applicazioni multi-tier 29-11 

codici di stato 33-12 

connessione all'application 
server 29-26 

header del messaggio 32-3 

header della richiesta 32-4, 
33-9, 42-4 

header della risposta 33-13, 
42-5 

messaggi di richiesta Vedere 

messaggi di richiesta 
messaggi di risposta Vedere 

messaggi di risposta 
panoramica 32-5-32-7 
SOAP 36-1 
HTTP, richieste 

immagini 34-40 
HTTP, risposte 



immagini 34-40 
httpsrvr.dll 29-11, 29-14, 29-26 
HyperHelp, visualizzatore 7-28 

I 

IApplicationObject, 

interfaccia 42-4 
IAppServer interface 
estensione 29-17 
transazioni 29-19 
XML, broker 29-34 
IAppServer, interfaccia 27-33, 
27-35, 28-3 - 28-4, 29-4, 29-5 
informazioni di stato 29-20 
provider locali 28-3 
provider remoti 28-3 
IAppServer, interface 

chiamata 29-29 
IAppServerSOAP, 

interfaccia 29-5,29-27 
icone 9-20, 29-26, 50-4 

aggiunta a component 45-15 
aggiunta a menu 8-23 
barre strumenti 8-50 
oggetti grafici 10-4 
viste ad albero 9-12 
IConnectionPoint, 
interfaccia 41-12 
IconnectionPoint, 
interfaccia 40-15 
IConnectionPointContainer, 

interfaccia 41-11,41-12 
IconnectionPointContainer, 

interfaccia 40-15 
IconnectionPointContainerlmpl, 

implementazione 41-11 
ICustomHelp Viewer 7-28, 7-29, 
7-30, 7-31 
implementazione 7-30 
IDE 

aggiunta di azioni 58-10 
aggiunta di immagini 58-9 - 

58-10 
cancellazione di 

pulsanti 58-10-58-11 
personalizzazione 58-1 
identificatori 

Vedi anche GUID 
caratteri significativi A-3 
costanti 10-13 
esterni A-3 
eventi 48-8 
impostazione delle 

proprieta 47-7 
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impostazione di 
proprieta 47-7 
lunghezza A-3 
membri dati 48-2 
metodi 49-2 
non validi 8-34 
risorse 52-4 
sensibilita maiuscole/ 

minuscole A-3 
tipi 10-13 
tipi di record dei 
messaggi 51-7 
IDispatch, interfaccia 38-9, 
38-21, 41-13 
Automation 38-13,40-14 
identificatori 41-14, 41-15 
Idispatch, interfaccia 41-14 - 
41-15 

IDL (Interface Definition 
Language) 31-5, 38-18, 38-20 
Type Library editor 39-8 

IDL, compilatore 38-20 

IDL, file 31-5,31-6 

CORBA Server Wizard 31-6 
CORBA, client 31-14 
esportazione da libreria di 
tipi 39-20 

IDL, file, 

compilazione 31-6 - 31-7 

IDOMImplementation 35-3 

IEEE 

formati in virgola 
mobile A-3 

IETF, protocolli e standard 32-3 

IExtendedHelpViewer 7-29, 

7- 33 

#ifdef, direttiva 14-18 
#ifndef, direttiva 14-19 
IHelpManager 7-29, 7-37 
IHelpSelector 7-29, 7-34 
IHelpSystem 7-29, 7-37 
IID 40-5 
Ilnterface 

gestione della durata 13-5 

implementazione 13-3, 13-4 
Ilnvokable 36-2 
IIS 42-1 

versione 42-3 
II 11-7 
Image Editor 

utilizzo 45-15 
Image, marcatore HTML 

(<IMG>) 33-15 
Imagelndex, proprieta 8-50, 

8- 52 



ImageList 8-21 

ImageMap, marcatore HTML 

(<MAP>) 33-15 
Images, proprieta 

pulsanti strumento 8-50 
IMarshal, interfaccia 41-15, 

41-17 
IME 16-9 

ImeMode, proprieta 16-9 
ImeName, proprieta 16-9 
immagini 9-20, 10-18, 19-2, 50-3, 
50-3 - 50-6 

aggiunta 10-18 

aggiunta a menu 8-38 

aggiunta di controlli per 6-13 

cambio 10-21 

cancellazione 10-23 

caricamento 10-20 

controlli per 10-2, 10-18 

copia 50-7 

disegno 54-9 

in frame 8-16 

internazionalizzazione 16-10 

modifica 10-21 

pennelli 10-10 

pulsanti strumento 8-50 

ridisegno 50-7 

riduzione dello 
sfarfallio 50-6 

salvataggio 10-21 

scorrimento 10-18 

sostituzione 10-21 

visualizzazione 9-19 
immagini, richieste 34-40 
Implementation 

Repository 31-4 
Import ActiveX Control, 

comando 40-2,40-4 
Import Type Library, 
comando 40-2,40-3 
ImportedConstraint, 

proprieta 23-12, 23-23 
impostazioni di proprieta 

lettura 47-9 

scrittura 47-9 
impostazioni locali 4-23 

formati dei dati e 16-10 

moduli di risorse 16-11 
impostazioni nazionali 16-2 
Include Unit Hdr, comando 8-4 
include, file 

ricerca A-7 
Increment, proprieta 9-6 
Indent, proprieta 8-50, 8-52, 
9-12 



Index Files editor 24-7 
index, parola riservata 55-8 
Index, proprieta 
campi 23-12 
IndexDefs, proprieta 22-41 
IndexFieldCount, 
proprieta 22-28 
IndexFieldNames, 
proprieta 22-28, 26-8, 27-9 
IndexNamee 22-29 
IndexFields, proprieta 22-28 
IndexFiles, proprieta 24-7 
IndexName, proprieta 24-7, 
26-7, 27-10 
IndexFieldNames e 22-29 
IndexOf, metodo 4-19, 4-20 
indicatore di posizione di 

file A-9 
indici 22-27 - 22-39, 47-9 
cancellazione 27-10 
dataset client 27-8 - 27-11 
elenco 21-15,22-28 
intervalli 22-32 
operazioni batch e 24-52, 

24-53 
ordinamento dei 

record 22-27-22-29,27-8 
raggruppamento di 
dati 27-10-27-11 
relazioni master/ 

detail 22-37 
ricerca su chiavi 
parziali 22-31 
specifica 22-28-22-29 
tabelle dBASE 24-6 - 24-8 
indici, definizioni 22-41 
indirizzamento delle richieste 

WebSnap 34-36 
indirizzi 

connessioni socket 37-3, 37-4 
Indy Clients, pagina 

(Component palette) 5-8 
Indy Misc, pagina (Component 

palette) 5-9 
Indy Servers, pagina 

(Component palette) 5-9 
INFINITE, costante 11-11 
informazioni di login 

specifica 21-5 
informazioni di schema 26-12 - 
26-18 
campi 26-16 
indici 26-16-26-17 
procedure registrate 26-15, 
26-17-26-18 
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tabelle 26-14-26-15 
informazioni di stato 9-16 
comunicazione 28-8, 29-20 - 
29-21 

eventi del mouse 10-25 
gestione 44-6 
oggetti transazionali 44-13 
proprieta condivise 44-7 
informazioni di tipo 38-17, 39-1 
dispinterface 41-13 
Guida 39-9 

importazione 40-2-40-7 
interfaccia IDispatch 41-14 
informazioni di tipo in 

esecuzione 46-8 
informazioni sulla versione 
controlli ActiveX 43-5 
informazioni di tipo 39-9 
Informix, driver 

distribuzione 17-10 
Inherit (Object Repository) 7-27 
inherited, parola chiave 13-8, 

13-11, 13-12, 13-14 
InheritsFrom, metodo 13-23 
.ini, file 14-7 

Win-CGI, applicazioni 32-7 
InitializeControl, metodo 43-12 
InitWidget, proprieta 14-13 
INITWIZARD0001 58-23 
Input Mask editor 23-15 
input method editor 16-9 
input, parametri 22-53 
input/output, parametri 22-53 
Insert From Resource, comando 

(Menu designer) 8-40, 8-45 
Insert from Resource, finestra di 

dialogo 8-45 
Insert From Template, comando 

(Menu designer) 8-40, 8-41 
Insert Template, finestra di 

dialogo 8-42 
Insert, comando (Menu 

designer) 8-40 
INSERT, istruzione 21-12 
INSERT, istruzioni 24-42, 24-45, 

28-10 

Insert, metodo 22-19, 22-20 

Append e 22-19 

menu 8-44 

stringhe 4-19 
InsertObject method 4-21 
InsertRecord, metodo 22-22 
InsertSQL, proprieta 24-42 
Install COM+ objects, 
comando 44-29 



Install Components,finestra di 

dialogo 45-20 
Install MTS objects, 

comando 44-29 
Install, comando 

(Component) 45-20 
installazione 

programmi 17-2 
supporto 1-3 
Installazione di oggetti 

transazionali 44-29 
InstallShield Express 2-5, 17-1 
distribuzione 

applicazioni 17-2 
BDE 17-9 
package 17-3 
SQL Links 17-10 
instanziazione 13-5 
int, tipi A-3 

INTAComponent 58-14 
INTAServices 58-8, 58-9, 58-18 
integer A-6 

array e A-5 

con segno A-5 

conversione in puntatori A-5 

divisione A-5 

enumerazioni e A-6 

puntatori e A-5 

right shifted A-5 
integer, tipi A-3 
IntegralHeight, proprieta 9-11, 
19-12 

integrita dei dati 18-5, 28-13 
integrita referenziale 18-5 
InterBase, driver 

distribuzione 17-10 
InterBase, pagina (Component 

palette) 5-8, 18-2 
InterBase, tabelle 24-9 
InterBaseExpress 14-23 
interceptor 38-5 
interfacce 7-13, 46-4, 46-7, 57-2, 
57-3 
ActiveX 38-21 

personalizzazione 43-8 - 
43-14 

aggiunta di metodi 41-10 - 
41-11 

aggiunta di proprieta 41-10 
API Tools 58-1, 58-4 - 58-7 
numeri di versione 58-12 
- 58-13 
application server 29-17- 

29-18, 29-29 
applicazioni distribuite 3-4 



Automation 41-13-41-15 
binding dinamico 31-4, 

39-10, 41-13 
COM 7-20, 38-1, 38-3 - 38-5, 
39-9 - 39-10, 40-1, 41-3, 41-9 
-41-15 
dichiarazioni 40-6 
eventi 41-11 
wrapper 40-6 
CORBA 31-2,31-5-31-13 
custom 41-15 
dichiarazione 13-2 
dispatch 41-14 
DOM 35-2 

elementi di programma non 

visuali 45-5 
estensione dell'eredita 

singola 3-4 
implementazione 38-6, 41-3 
in esecuzione 46-7 
in progettazione 46-8 
inuscita 41-11,41-12 
internazionalizzazione 16-9, 

16-10, 16-13 
librerie di tipi 38-19, 40-6, 

41-9 

multipla, eredita 13-2 
oggetti evento COM+ 44-25 
proprieta, dichiarazione 57-4 
registrazione 31-13 - 31-14 
richiamabili 36-2 - 36-10 
sistema di Help 7-29 
sistemi di Help 7-29 
skeleton 31-3 
stub 31-2,31-3 
Type Library editor 39-9 - 

39-10, 39-14, 41-9 
Web Services 36-1 
XML, nodi 35-5 

interfacce del componente 
creazione 57-3 
proprieta, dichiarazione 57-4 

interfacce duali 41-13 - 41-14 
Active Server Objects 42-3 
chiamata a metodi 40-14 
compatibilita dei tipi 41-16 
oggetti transazionali 44-3, 

44-19 
parametri 41-16 

interfacce in esecuzione 46-7 

interfacce in progettazione 46-8 

interfacce richiamabili 
chiamata 36-17-36-18 
implementazione 36-12- 
36-14 
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namespace 36-3 
registrazione 36-3 
interfacce utente 8-1, 18-16 - 
18-17 

a singolo record 19-8 
isolamento 18-6 
layout 8-4-8-5 
multirecord 19-16 
organizzazione dei dati 19-8, 

19-16 
schede 8-1-8-4 

interface 13-2, 36-3 

Interface Definition Language 

Vedere IDL 
Interface Repository 

registrazione di interfacce 
CORBA 31-13 
INTERFACEJJUID, 

macro 13-3,36-3 
InternalCalc, campi 23-6, 27-11 
- 27-12 
indicie 27-10 
internazionalizzazione di 
applicazioni 16-1 
abbreviazioni 16-9 
conversione input di 

tastiera 16-9 
localizzazione 16-12 
Internet Engineering Task 

Force 32-3 
Internet Information Server 
(IIS) 42-1 
versione 42-3 
Internet, pagina (Component 

palette) 5-8 
Internet, server 32-1 - 32-12 
Internet, standard e 

protocolli 32-3 
InternetExpress 7-19, 29-33 - 
29-43 

e ActiveForms 29-31 - 29-32 
InternetExpress, pagina 

(Component palette) 5-8 
intervalli 22-32-22-36 

annullamento 22-36 

applicazione 22-36 

e filtri 22-32 

indicie 22-32 

limiti estremi 22-35 

modifica 22-35-22-36 

specifica 22-32-22-35 

valori nulli 22-33, 22-34 
intestazioni 

owner-draw 6-12 
intranet 



Vedere reti locali 
nomihost 37-4 
InTransaction, proprieta 21-7 
Invalidate, metodo 54-10 
invio di messaggi 51-8-51-11 
Invoke, metodo 41-14 
invoker 36-12 
InvokeRegistry.hpp 36-5 
IObjectContext, interfaccia 42-3, 

44-4, 44-5 
metodi per terminare una 
transazione 44-13 
IObjectControl, 

interfaccia 38-15, 38-16, 44-2 
IoleClientSite, interfaccia 40-17 
IOleDocumentSite, 

interfaccia 40-17 
iostream A-9 
IOTAActionServices 58-8 
IOTABreakpointNotifier 58-19 
IOTACodeCompletionServices 

58-8 

IOTAComponent 58-14 
IOTACreator 58-15 
IOTADebuggerNotifier 58-19 
IOTADebuggerServices 58-8 
IOTAEditLineNotifier 58-19 
IOTAEditor 58-14 
IOTAEditorNotifier 58-19 
IOTAEditorServices 58-8 
IOTAFile 58-15,58-17 
IOTAFormNotifier 58-19 
IOTAFormWizard 58-3 
IOTAIDENotifier 58-19 
IOTAKeyBindingServices 58-8 
IOTAKeyboardDiagnostics 58-8 
IOTAKeyboardServices 58-8 
IOTAMenuWizard 58-3 
IOTAMessageNotifier 58-19 
IOTAMessageServices 58-8 
IOTAModule 58-13 
IOTAModuleNotifier 58-19 
IOTAModuleServices 58-8, 

58-13 
IOTANotifier 58-19 
IOTAPackageServices 58-8 
IOTAProcessModNotifier 58-19 
IOTAProcessNotifier 58-19 
IOTAProjectWizard 58-3 
IOTAServices 58-8 
IOTAThreadNotifier 58-19 
IOTAToDoServices 58-8 
IOTAToolsFilter 58-8 
IOTAToolsFilterNotifier 58-19 
IOTAWizard 58-2, 58-3 



IOTAWizardServices 58-8 
IP, indirizzi 37-4, 37-6 

host 37-4 

nomi host e 37-5 
IprovideClassInfo, 
interfaccia 38-19 
IProviderSupport, 
interfaccia 28-2 
IPX/SPX, protocolli 37-1 
Irequest, interfaccia 42-4 
Iresponse, interfaccia 42-5 
is, operatore 13-23 
isalnum, funzione A-8 
isalpha, funzione A-8 
ISAPIDLLs 17-10 
ISAPI, applicazioni 32-7 

creazione 33-1,34-9 

debug 32-11 

messaggi di richiesta 33-2 
iscntrl, funzione A-8 
IScriptingContext, 

interfaccia 42-3 
ISecurityProperty, 
interfaccia 44-18 
Iserver, interfaccia 42-7 
ISessionObject, interfaccia 42-6 
islower, funzione A-8 
isolamento 

transazioni 18-5,44-11 
ISpecialWinHelpViewer 7-29 
isprint, funzione A-8 
IsSecurityEnabled 44-17 
istanze 48-2 
istanziazione 

COM, server 41-9 
istruzioni di assegnazione 47-2 
isupper, funzione A-8 
IsValidChar, metodo 23-18 
ItemHeight, proprieta 9-11 

caselle combinate 19-12 

caselle di riepilogo 19-12 
Itemlndex, proprieta 9-11 

gruppi di pulsanti di 
opzione 9-14 
Items, proprieta 

caselle di riepilogo 9-11 

controlli pulsanti di 
opzione 19-15 

gruppi di pulsanti di 
opzione 9-14 
ITypeComp, interfaccia 38-19 
ITypelnfo, interfaccia 38-19 
ITypeInfo2, interfaccia 38-19 
ItypeLib, interfaccia 38-19 
ITypeLib2, interfaccia 38-19 
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IUnknown 

implementazione 13-4 
IUnknown, interfaccia 38-3, 
38-20 

controller Automation 41-14 
Iunknown, interfaccia 38-4 
gestione della durata 13-5 
implementazione 13-3 
supporto ATL 38-24 - 38-25 
traccia delle chiamate 41-9 
IXMLNode 35-4 - 35-6, 35-7 

J 

javascript, librerie 29-33, 29-35 
individuazione 29-34, 29-35 

just-in-time, attivazione 29-7, 
44-5 
attivazione 44-5 

K 

K, note a pie di pagina (sistemi 

diGuida) 52-5 
KeepConnection, 

proprieta 21-3, 21-13, 24-19 
KeepConnections, 

proprieta 24-14,24-19 
key-down, messaggi 48-5, 56-9 
KeyDown, metodo 51-14, 56-10 
KeyExclusive, proprieta 22-31, 

22-35 

KeyField, proprieta 19-13 
KeyFieldCount, proprieta 22-31 
KeyPress, metodo 51-14 
KeyString, metodo 51-14 
KeyUp, metodo 51-14 
KeyViolTableName, 

proprieta 24-55 
KeywordHelp 7-36 
Kind, proprieta 

pulsanti bitmap 9-8 

L 

Last, metodo 22-6 
lato server 

scripting 34-33-34-36 
Layout, proprieta 9-8 
Left, proprieta 8-4 
LeftCol, proprieta 9-18 
lettura dell'impostazione delle 

proprieta 47-7 
.lib, file 15-2,15-14 

package 15-14 
$LIBPREFIX, direttiva 7-11 



LibraryName, proprieta 26-4 
libreria di esecuzione 4-1 
librerie 

controlli personalizzati 45-5 
eccezioni 12-19 
librerie di componenti 
aggiunta di 
componenti 45-20 
librerie di importazione 7-11, 

7-12, 7-15 
librerie di tipi 38-11, 38-17 - 
38-20, 39-21 
accesso 38-19, 39-14, 40-2 - 
40-7 

Active Server Objects 42-3 

aggiunta 

metodi 39-15-39-16 
proprieta 39-15-39-16 

aggiunta di interfacce 39-14 

apertura 39-14 

browser 38-19 

consultazione 38-20 

contenuti 38-17, 39-1, 40-5 - 
40-7 

controlli ActiveX 43-3 
creazione 38-18,39-13- 

39- 14 

deregistrazione 38-20 
disinstallazione 38-19 
distribuzione 39-20 - 39-21 
exporting as IDL 39-20 
generate dai wizard 39-1 
IDL e ODL 38-18 
importazione 40-2-40-7 
inclusione come 

risorse 39-20 - 39-21, 43-3 
interfacce 38-19 
modifica di interfacce 39-15 

- 39-16 
oggetti transazionali 44-3 
ottimizzazione delle 

prestazioni 39-9 
quando utilizzarle 38-18 - 

38-19 

registrazione 38-20, 39-20 
registrazione di oggetti 38-19 
salvataggio 39-19 
strumenti 38-20 
tipivalidi 39-12-39-13 
unit _TBL 38-25, 39-2, 39-14, 

40- 2, 40-5-40-7,41-15 
vantaggi 38-19-38-20 

$LIBSUFFIX, direttiva 7-11 
$LIBVERSION, direttiva 7-11 
.lie, file 43-7 



linee 

cancellazione 10-30 
disegno 10-6, 10-10, 10-10 - 
10-11, 10-29-10-30 
cambio dello spessore 

della penna 10-6 
gestori di evento 10-27 
Lines, proprieta 9-3, 47-8 
LineSize, proprieta 9-6 
LineTo, metodo 10-5, 10-8, 

10-11, 50-3 
link 7-12 

link dinamico 7-11, 7-12, 7-13 
link ipertestuali 

aggiunta a HTML 33-15 
Link, marcatore HTML (</ 

A>) 33-15 
Linux 

applicazioni 
multipiattaforma 14-1 - 
14-30 

directory 14-16 

e Windows 14-14-14-16 

file batch 14-14 

notifiche di sistema 51-11 - 
51-16 

Registry 14-15 
List, proprieta 24-30 
liste 

accesso 4-15 

aggiunta 4-14 

cancellazione 4-14 

disposizione 4-15 

persistenti 4-15 

raccolte 4-16 

stringhe 4-15, 4-16 - 4-21 
liste di stringhe 

persistenti 4-15 
ListField, proprieta 19-14 
ListSource, proprieta 19-13 
livelli di raggruppamento 27-10 

aggregati di 
manutenzione 27-14 
Loaded, metodo 47-14 
LoadFromFile, metodo 

datasetADO 25-15 

dataset client 18-10, 27-36 

grafici 10-20,50-4 

stringhe 4-16 
LoadFromStream, metodo 

dataset client 27-36 
LoadLibrary 7-11 
LoadPackage, funzione 15-4 
LoadParamListltems, 
procedura 21-15 
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LoadParamsFromlniFile, 

metodo 26-5 
LoadParamsOnConnect, 

proprieta 26-5 
Local SQL 24-9,24-10 

query eterogenee 24-9 
locale, date A-12 
locale, orario A-12 
LocalHost, proprieta 
socket client 37-7 
localizzazione 

localizzazione di 

applicazioni 16-2 
risorse 16-11, 16-13 
localizzazione di 

applicazioni 16-13 
localizzazioni 16-13 
LocalPort, proprieta 
socket client 37-7 
Locate, metodo 22-11 
Lock, metodo 11-8 
LockList, metodo 11-8 
LockType, proprieta 25-12, 
25-13 

LogChanges, proprieta 27-5, 

27-37 
login 

connessioni SOAP 29-27 
connessioni Web 29-26 
login, eventi 21-5 
Login, finestra di dialogo 21-4 
login, obbligatorio 34-30 - 34-31 
LoginPrompt, proprieta 21-4 
Lookup, metodo 22-12 
LookupCache, proprieta 23-10 
LookupDataSet, proprieta 23-12 
LookupKeyFields, 

proprieta 23-10,23-12 
LookupResultField, 

proprieta 23-12 
Lparam, parametro 51-10 
.lpk, file 43-8 
LPK_TOOL.EXE 43-8 
lunghezza zero, file A-9 

M 

m_spObjectContext 44-4 

m_VclCtl 43-10 

macro 13-18, 13-21, 13-29, 51-4 
espansione A-8 
HANDLEJVISG 51-2 

main, funzione A-2 

MainMenu, componente 8-33 

Main WndProc, metodo 51-3 



maiuscole/ minuscole, 
sensibilita 

indici 27-9 
make, utilita 

Linux 14-16 
malloc, funzione A-ll 
Man, pagine 7-28 
mappatura 

XML 30-2-30-4 
definizione 30-4 
mappe di interfacce 38-24 
mappe di oggetti 38-24 
mappe di tastiera 16-9, 16-10 
Mappings, proprieta 24-53 
Margin, proprieta 9-8 
marshaling 38-8 

custom 41-17 

interfacce COM 38-8 - 38-9, 

41-4, 41-15-41-17 
interfacce CORBA 31-3 
interfaccia IDispatch 38-13, 

41-15 

oggetti transazionali 44-3 
maschere 23-15 
master/ detail, relazioni 19-16, 
22-36 - 22-39, 22-49 - 22-50 

aggiornamenti in 
cascata 28-6 

applicazioni multi-tier 29-19 

cancellazioni in cascata 28-6 

dataset client 27-20 

dataset unidirezionali 26-12 

indici 22-37 

inegrita referenziale 18-6 
tabelle annidate 22-38 - 
22-39, 29-20 
master / detail, schede 19-16 

esempio 22-37-22-38 
MasterFields, proprieta 22-37, 
26-12 

MasterSource, proprieta 22-37, 
26-12 

matematiche, funzioni 
errori di dominio A-8 
errori underflow A-8 
Max, proprieta 

barre di avanzamento 9-17 
trackbar 9-5 
MaxDimensions, 
proprieta 20-20 
MaxLength, proprieta 9-3 
controlli memo data- 
aware 19-9 
controlli rich edit data- 
aware 19-10 



MaxRecords, proprieta 29-37 
MaxRows, proprieta 33-20 
MaxStmtsPerConn, 

proprieta 26-3 
MaxSummaries, 

proprieta 20-20 
MaxTitleRows, proprieta 19-26 
Max Value, proprieta 23-12 
MBCS 4-21 
MDAC 17-7 
MDI applicazioni 

menu attivo 8-44 
MDI, applicazioni 7-1 - 7-3 
creazione 7-2 

fusione di menu 8-44 - 8-45 
media player 5-7, 10-33 - 10-35 

esempio 10-34 
medie, cubi decisionali 20-5 
membri dati 3-2 

assegnazione del nome 48-2 

inizializzazione 13-12 

strutture dei messaggi 51-5 
memo, controlli 6-7, 9-3, 47-8 

modifica 53-1 
memorizzazione delle risorse 

nella cache 50-2 
menu 8-32-8-44 

accesso a comandi 8-36 

aggiunta 8-33, 8-37 - 8-38 

aggiunta di immagini 8-38 

assegnazione dei nomi 8-33 

dasttivazione di 
elementi 6-10 

definizione 8-19 

gestione di eventi 5-6, 8-43 

importazione 8-45 

internazionalizzazione 16-9, 
16-10 

liste di azioni 8-19 

modelli 8-33, 8-40, 8-41, 8-42 

owner-draw 6-12 

popup 6-11 

riutilizzo 8-40 

salvataggio come 
modelli 8-41, 8-42 - 8-43 

scorciatoie 8-36 - 8-37 

spostamento di 
elementi 8-38 

spostamento tra 8-40 

visualizzazione 8-39, 8-40 
menuadiscesa 8-37-8-38 
menu contestuali 

aggiunta di elementi 52-17 - 
52-18 

barre strumenti 8-52 
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Menu designer 8-40 
Menu designer 5-6, 8-32 - 8-37 

menu contestuali 8-40 
menu popup 6-11 - 6-12 

menu a discesa e 8-37 

visualizzazione 8-39 
Menu, proprieta 8-44 
menu, wizard 58-4 
MergeChangeLog, 

metodo 27-7,27-37 
mesi, restituzione del 

corrente 55-9 
MESSAGE_HANDLER, 

macro 51-4 
MESSAGE_MAP, macro 51-8 
messages.hpp, file 51-2 
messaggi 51-8, 55-4, A-ll 

applicazioni 
multithread 51-10 

definiti dell'utente 51-6, 51-8 

definizione 51-1 

identificatori 51-7 

intercettazione 51-5 

invio 51-8-51-11 

Linux Vedere notifiche di 
sistema 

mouse 56-9 

mouse- e key-down 56-9 
record 

tipi, dichiarazione 51-7 
strutture 51-5 
tasto 56-9 

Windows 51-1-51-11 
messaggi definiti 

dell'utente 51-6,51-8 
messaggi del mouse 56-9 
messaggi di errore A-8, A-ll, 

A-12 

internazionalizzazione 16-11 
messaggi di richiesta 33-2, 33-3, 
42-4 

contenuti 33-11 

dispatch 33-5 

elementi di azione e 33-6 

HTTP, panoramica 32-5 - 
32-7 

informazioni 
dell'header 33-9 - 33-11 

risposta a 33-8 - 33-9, 33-13 

tipi 33-10 

trattamento 33-5 

XML, broker 29-37 
messaggi di risposta 33-3, 42-5 

contenuti 33-13,33-14 



creazione 33-11-33-13, 
33-14 

informazioni database 33-18 

- 33-21 
informazioni 

dell'header 33-11-33-13 
informazioni di stato 33-12 
trasmissione 33-8, 33-13 
messaggi diagnostici 

(ANSI) A-l 
messaggi key-down 56-9 
messaggi, header (HTTP) 32-4 
metadati 21-14-21-15 
dbExpress 26-12-26-18 
modifica 26-11-26-12 
ottenimento da 
provider 27-29 
metafile 9-20, 10-1, 10-20, 50-4 

quando usarli 10-4 
Method, proprieta 33-10 
MethodAddress, metodo 13-23 
MethodType, proprieta 33-7, 
33-10 

metodi 3-3, 10-16, 45-7, 49-1, 
55-12 
aggiunta a controlli 

ActiveX 43-9-43-11 
aggiunta a interfacce 41-10 - 
41-11 

assegnazione dei nomi 49-2 
cancellazione 5-6 
chiamata 48-6, 49-3, 54-5 
dichiarazione 10-16, 46-10, 
49-4 
public 49-3 
disegno 54-9,54-10 
ereditati 48-6 

gestione dei messaggi 51-3, 
51-5 

gestione di messaggi 51-1 
gestori di evento 48-5 

ridefinizione 48-6 
grafici 50-3, 50-4, 50-6, 50-7 

tavolozze 50-5, 50-6 
inizializzazione 47-14 
proprieta e 47-5 - 47-7, 49-1, 

49-2, 54-4 
protected 49-3 
public 49-3 

ridefinizione 51-4, 51-5, 51-8, 

55-13 
virtual 46-9,49-4 
virtuali 

eredita 13-2 
metodi di elementi grafici 



tavolozze 50-6 
Microsoft Server DLL 32-7 

creazione 33-1,34-9 

messaggi di richiesta 33-2 
Microsoft SQL Server 

distribuzione di driver 17-10 
Microsoft Transaction 

Server 7-20 
Microsoft Transaction Server 

Vedere MTS 
midas.dll 27-1, 29-3 
midaslib.dcu 17-7,29-3 
MIDI, file 10-34 
MIDL 38-20 

Vedi anche IDL 
MIME, messaggi 32-6 
MIME, tipi e costanti 10-23 
Min, proprieta 

barre di avanzamento 9-17 

trackbar 9-5 
MinSize, proprieta 9-7 
MinValue, proprieta 23-13 
misure 

conversione 4-27-4-35 

unita 4-30 
MM, film 10-34 
mobile computing 18-15 
modali, schede 8-5 
modalita di disegno 10-30 
modalita di modifica 22-18 
modalita edit 

annullamento 22-18 
Mode, proprieta 24-51 

penne 10-6 
modelli 7-25,7-27 

cancellazione 8-41 

componente 8-12 

componenti 8-13 

grafici decisionali 20-17 

HTML 33-14-33-18 

menu 8-33,8-40,8-41 

produttori di pagine 34-4 

programmazione 7-3 

Web Broker, 
applicazioni 33-2 
modelli di componente 8-13, 
46-2 

e frame 8-15,8-16 
modelli di componenti 8-12 
modelli di risposta 33-14 
modelli di threading 41-5 - 41-9 

controlli ActiveX 43-5 

moduli dati remoti 29-15 

moduli dati 
transazionali 29-16 
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oggetti Automation 41-5 
oggettiCOM 41-3 
oggetti transazionali 44-19 - 
44-20 

registro di sistema 41-6 
modello a oggetti 13-1 
modifica di script 34-35 
Modified, metodo 56-12 
Modified, proprieta 9-3 
Modifiers, proprieta 9-7 
Modify Alias, metodo 24-26 
ModifySQL, proprieta 24-42 
moduli 

API Tools 58-3, 58-13 - 58-14 

tipi 7-21 

tipiWeb 34-2 

Type Library editor 39-11, 
39-18 - 39-19 
moduli dati 18-7 

accesso da schede 7-24 

applicazioni Web e 33-2 

componenti database 24-17 

creazione 7-22 

editing 7-22 

remoti e standard 7-21 

Web 34-3,34-5 

Web Broker, 
applicazioni 33-4 
moduli dati remoti 29-3, 29-13, 
29-14 - 29-17 

basatisuCOM 29-5,29-22 

centralizzazione 29-8 - 29-9 

classe di 
implementazione 29-14 

figlio 29-22 

genitore 29-22 

modelli di threading 29-15, 
29-16 

multipli 29-21 - 29-22, 29-30 
oggetto di 

implementazione 29-5 
senza stato 29-8, 29-9, 29-20 - 

29-21 

moduli dati transazionali 29-7 - 
29-8 
attributi della 

transazione 29-16 
connessioni a database 29-6, 
29-8 

centralizzazione 29-7 

interfaccia 29-18 

modelli di threading 29-16 

sicurezza 29-10 
moduli di fusione 17-3 
moduli di risorsa 16-10 



moduli di risorse 16-11 
moduli Web 33-2-33-3 
aggiunta di sessioni 

database 33-18 
DLL e, avvertenze 33-3 
Month, proprieta 55-6 
MonthCalendar, 

componente 9-13 
motivi 10-10 

motivi di riempimento 10-8, 
10-9 

motori di database 

di terze parti 17-7 
mouse, eventi 10-25 - 10-27 

controllodi 10-27 

definizione 10-25 

drag-and-drop 6-1 - 6-4 

informazioni di stato 10-25 

parametri 10-25 
mouse, puntatori 

drag-and-drop 6-4 
mouse-down, messaggi 56-9 
MouseDown, metodo 51-14, 
56-9 

MouseMove, metodo 51-14 
MouseToCell, metodo 9-18 
MouseUp, metodo 51-14 
.mov, file 10-34 
Move method 

elenchi di stringhe 4-20, 4-21 
MoveBy, metodo 22-7 
MoveCount, proprieta 24-54 
MoveFile, funzione 4-9 
MovePt 10-30 
MoveTo, metodo 10-5, 10-8, 

50-3 
.mpg, file 10-34 
Msg, parametro 51-4 
MSI, tecnologia 17-3 
MTS 7-20, 29-7, 38-11, 38-15, 

44-1 

Vedi anche oggetti 
transazionali 
ambiente di esecuzione 44-2 
COM+ e 44-2 

oggetti transazionali 38-15 - 

38-16 
requisiti 44-3 

riferimenti a oggetti 44-27 - 
44-28 

server in-process 44-2 

transazioni 29-18 
MTS executive 44-2 
MTS Explorer 44-30 
MTS, package 44-7,44-29 



multibyte, caratteri 
(MBCS) 14-21, A-2, A-4 
applicazioni 
multipiattaforma 14-18 
multibyte, codici di 

caratteri 16-3 
multibyte, set di caratteri 16-3 
multimedia, applicazioni 10-30 

- 10-35 
multipagina, finestre di 

dialogo 9-16 
multipiattaforma, 
applicazioni 14-1 - 14-30 
azioni 8-20 
creazione 14-1 
database 14-21-14-29 
Internet 14-30 
multi-tier 29-11 
porting in Linux 14-2 - 14-21 
multiple document interface 7-1 
-7-3 

multi-read exclusive-write 
synchronizer 
avvertenze sull'uso 11-9 
MultiSelect, proprieta 9-11 
multi-thread, applicazioni 11-1 
multithread, applicazioni 

invio di messaggi 51-10 
multi-tier, applicazioni 18-3, 
18-13 

architettura 29-4,29-5 

distribuzione 17-10 

multipiattaforma 29-11 

panoramica 29-3-29-4 

parametri 27-30 

relazioni master/ 
detail 29-19 
Multitier, pagina (finestra di 

dialogo New Items) 29-2 
mutexes 

CORBA 31-12 
MyBase 27-35 
MyEventJD, tipo 51-16 

N 

Name, proprieta 

campi 23-13 

parametri 22-54,22-55 

voci di menu 5-6 
namespace 45-14 

interfacce richiamabili 36-3 
nastri audio digitali 10-34 
native tools API 58-2, 58-9 - 

58-12 
navigator 
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suggerimenti 19-34 
navigatore 19-2, 19-31 - 19-34, 
22-6 

attivazione/disattivazione 
dei pulsanti 19-32, 19-33 
cancellazione dei dati 22-21 
condivisione fra 
dataset 19-34 
editing 22-18 
pulsanti 19-32 
NDX, indici 24-7 
.Net 

Web Services 36-1 
NetCLX 7-17 

definizione 14-6 
NetFileDir, proprieta 24-25 
Netscape Server DLL 

creazione 33-1 
neutral, modello di 

threading 41-8-41-9 
New Field, finestra di 
dialogo 23-6 
definizione dei campi 23-7, 

23-9, 23-11 
Field, proprieta 23-6 
Field, tipo 23-6 
Lookup, definizione 23-7 
Dataset 23-9 
Key Fields 23-9 
Lookup Keys 23-9 
Result Field 23-10 
New Items, finestra di 

dialogo 7-25, 7-26, 7-27 
New Thread Object, finestra di 

dialogo 11-2 
New Unit, comando 45-12 
New, comando 45-12 
newline, caratteri A-9 
NewValue, proprieta 24-40, 

28-12 
Next,metodo 22-7 
NextRecordSet, metodo 22-57, 
26-9 

nodefault, parola chiave 47-8 
nomi delle connessioni 26-4 - 
26-6 

nomi di driver 24-14 
nomi di file 

ricerca A-7 
nomi di host 37-4 
nomi di percorso 

Linux 14-16 
nomi host 

indirizzi IP e 37-5 
nomi, connessioni 



cancellazione 26-5 

definizione 26-5 

modifica 26-6 
non connesso, modello 18-15 
non indicizzati, dataset 22-23 
non modali, schede 8-5, 8-7 
non visuali, componenti 45-5, 
57-3 

no-nonsense license 

agreement 17-17 
NOT NULL UNIQUE, 

vincolo 28-13 
NOT NULL, vincolo 28-13 
note di rilascio 17-17 
notificatori 58-3 
API Tools 

notificatori 58-19 - 58-23 
scrittura 58-22 
notifiche di sistema 51-11 - 

51-16 
NotifylD 7-30 
NSAPI, applicazioni 32-7 
creazione 33-1, 34-9 
debug 32-11 

messaggi di richiesta 33-2 
null, caratteri A-9 
NULL, macro A-8 
NULL, puntatori A-8 
null, valori 

intervalli 22-33 
numeri 47-2 

internazionalizzazione 16-10 

valori della proprieta 47-12 
NumericScale, proprieta 22-48, 

22-54, 22-55 
numero di contesto (Help) 9-17 
NumGlyphs, proprieta 9-8 



OAD 31-4,31-14 
.obj, file 15-2, 15-14 

package 15-14 
Object Activation Daemon 

Vedere OAD 
Object Broker 29-27 
Object Inspector 5-2, 47-2, 52-7 

editing di proprieta 
array 47-3 

guida con 52-4 

selezione di menu 8-41 
Object Management Group 

Vedere OMG 
Object Pascal 

modello a oggetti 13-1 
Object Repository 7-25 - 7-28 



aggiunta di elelementi 7-26 
componenti database 24-17 
specifica della directory 

condivisa 7-26 
utilizzo di elementi 7-26 - 

7-27 
wizard 58-4 
Object Repository, finestra di 

dialogo 7-25 
Object Repository, wizard 58-4 
Object, marcatore HTML 

(<OBJECT>) 33-15 
ObjectBroker, proprieta 29-25, 

29-26, 29-27 
ObjectContext, proprieta 
Active Server Objects 42-3 
esempio 44-16 
Objects, proprieta 9-18 

elenchi di stringhe 4-20, 6-16 
ObjectView, proprieta 19-24, 

22-39, 23-25 
Occultamento di elementi e 
categorie non utilizzati nelle 
bande di azioni 8-24 
.ocx, file 17-5 
ODBC, driver 

uso con ADO 25-1, 25-2 
utilizzo con BDE 24-1 
ODBC, drivers 

utilizzo con BDE 24-16 
ODL (Object Description 

Language) 38-18 
OEM, set di caratteri 16-3 
OEMConvert, proprieta 9-3 
oggetti 

Vedi anche COM, oggetti 
argomenti delle 
funzioni 13-8 
copia 13-6 

costruzione 13-8 - 13-13, 
14-13 

distribuiti 31-1 

drag and drop 6-1 

eredita 3-4-3-5 

inizializzazione 10-14 

posseduti 54-6-54-9 
inizializzazione 54-7 

scrip 34-35 

senza stato 44-13 

temporanei 50-6 

TObject 3-6 

volatili, accesso A-6 
oggetti associati ai thread 11-5 
oggetti Automation 38-13 
oggetti campo 23-1 - 23-29 
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accesso ai valori 23-21 - 

23-22 
cancellazione 23-11 
definizione 23-5 - 23-11 
dinamici 23-2-23-3 
e persistenti 23-2 
eventi 23-16-23-17 
persistenti 23-3-23-17 

e dinamici 23-2 
proprieta 23-1,23-11-23-16 

in esecuzione 23-13 
visualizzazione e modifica di 
proprieta 23-12 
oggetti comando 25-17 - 25-20 
oggetti contenuti 38-9 
oggetti esterni 38-9 
oggetti evento 11-10 
oggetti grafici 
thread 11-5 
oggetti immagine 50-4 
oggetti interni 38-9 
oggetti posseduti 54-6 - 54-9 

inizializzazione 54-7 
oggetti richiesta 
informazioni 
dell'header 33-4 
oggetti thread 
definizione 11-2 
inizializzazione 11-3 
oggetti thread-safe 11-5 
oggetti transazionali 38-11, 
38-15 - 38-16, 44-1 - 44-30 
amministrazione 38-16, 

44-30 
attivita 44-20 - 44-22 
callback 44-28 
caratteristiche 44-2 - 44-3 
condivisione di connessioni 

database 44-6 
condivisione di 

proprieta 44-7-44-9 
contesti di oggetto 44-4 
creazione 44-18-44-22 
debug 44-28-44-29 
disattivazione 44-5 
gestione delle risorse 44-3 - 
44-10 

installazione 44-29 - 44-30 
interfacce duali 44-3 
librerie di tipi 44-3 
marshaling 44-3 
requisiti 44-3 
rilascio di risorse 44-9 
senza stato 44-13 
sicurezza 44-17-44-18 



transazioni 44-5, 44-10 - 
44-17 
oggetto drag 6-4 
OldValue, proprieta 24-40, 

28-12 
OLE 

combinazione di menu 8-44 

contenitori 5-7 
OLE DB 25-1, 25-2 
OleFunction, metodo 40-15 
OleObject, proprieta 43-15, 
43-16 

OleProcedure, metodo 40-15 
OlePropertyGet, metodo 40-15 
OlePropertyPut, metodo 40-15 
OLEView 38-20 
OMG 31-1,31-5 
OnAccept, evento 37-8, 37-9 

socket server 37-10 
OnAction, event 33-8 
OnAfterPivot, evento 20-10 
OnBeforePivot, evento 20-9 
OnBeginTransComplete, 

evento 21-7,25-8 
OnCalcFields, evento 22-24, 

23-7,23-8, 27-11, 27-12 
OnCellClick, evento 19-29 
OnChange, evento 23-17, 50-7, 

54-8, 55-13, 56-12 
OnClick, evento 9-8, 48-1, 48-2, 

48-5 
menu 5-6 
OnColEnter, evento 19-29 
OnColExit, evento 19-29 
OnColumnMoved, 

evento 19-21,19-29 
OnCommitTransComplete, 

evento 21-9, 25-8 
OnConnect, evento 37-9 
OnConnectComplete, 

evento 25-8 
OnConstrainedResize, 

evento 8-5 
OnDataChange, evento 19-4, 

56-8, 56-11 
OnDataRequest, evento 27-34, 

28-3, 28-13 
OnDblClick, evento 19-29, 48-5 
OnDecisionDrawCell, 

evento 20-13 
OnDecisionExamineCell, 

evento 20-13 
OnDeleteError, evento 22-21 
OnDisconnect, evento 25-8, 

37-7, 37-8 



OnDragDrop, evento 6-3, 19-29, 
48-5 

OnDragOver, evento 6-2, 19-29, 
48-5 

OnDrawCell, evento 9-18 
OnDrawColumnCell, 

evento 19-29 
OnDrawDataCell, evento 19-29 
OnDrawItem, evento 6-16 
OnEditButtonClick, 

evento 19-23,19-29 
OnEditError, evento 22-18 
OnEndDrag, evento 6-3, 19-29, 

48-5 

OnEndPage, metodo 42-3 
OnEnter, evento 19-30, 48-5 
OnError, evento 37-8 
OnExecuteComplete, 

evento 25-8 
OnExit, evento 19-30, 56-13 
OnFilterRecord, evento 22-14, 

22-16 

OnGetData, evento 28-8 
OnGetDataSetProperties, 

evento 28-7 
OnGetTableName, 

evento 24-11, 27-23, 28-13 
OnGetText, evento 23-16, 23-17 
OnGetThread, evento 37-9 
OnHandleActive, evento 37-9 
OnHTMLTag, evento 29-42, 

33-16, 33-17, 33-18 
Onldle, gestore evento 11-5 
OnlnfoMessage, evento 25-9 
OnKeyDown, evento 19-30, 

48-5, 51-13, 56-10 
OnKeyPress, evento 19-30,48-5, 

51-13 

OnKey String, evento 51-13 
OnKeyUp, evento 19-30, 48-5, 
51-13 

OnLayoutChange, evento 20-9 
OnListening, evento 37-9 
OnLogin, evento 21-5 
OnMeasureltem, evento 6-15 
OnMouseDown, evento 10-25, 
10-26, 48-5, 51-13, 56-9 
parametri passati a 10-25, 
10-26 

OnMouseMove, evento 10-25, 
10-27, 48-5, 51-13 
parametri passati a 10-25, 
10-26 

OnMouseUp, evento 10-15, 
10-25, 10-26, 48-5, 51-13 
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parametri passati a 10-25, 
10-26 

OnNewDimensions, 

evento 20-9 
OnNewRecord, evento 22-19 
OnPaint, evento 9-20 
OnPassword, evento 24-14, 

24-23 

OnPopup, evento 6-12 
OnPostError, evento 22-21 
OnReceive, metodo 37-8, 37-10 
OnReconcileError, 
evento 14-29, 24-34, 27-22, 

27- 25 

OnRefresh, evento 20-7 
OnRequestRecords, 

evento 29-37 
OnRollbackTransComplete, 

evento 21-9,25-8 
OnScroll, evento 9-5 
OnSend, metodo 37-8, 37-10 
OnSetText, evento 23-17 
OnSetText,evento 23-16, 23-17 
OnStartDrag, evento 19-30 
OnStartPage, metodo 42-3 
OnStartup, evento 24-18 
OnStateChange, evento 19-5, 

20-9, 22-4 
OnSummaryChange, 

evento 20-9 
OnTerminate, evento 11-7 
OnTitleClick, evento 19-30 
OnTranslate, evento 30-7 
OnUpdateData, evento 19-4, 

28- 8, 28-9 
OnUpdateError, evento 14-29, 

24-34, 24-39 - 24-41, 27-25, 
28-12 

OnUpdateRecord, evento 24-34, 

24- 38 - 24-39, 24-42, 24-48 
On Validate, evento 23-17 
OnWillConnect, evento 21-5, 

25- 8 

open array 13-17 

temporanei 13-18 
Open Tools API Vedere API 

Tools 
Open, metodo 

componenti 
connessione 21-3 

dataset 22-4 

query 22-50 

sessioni 24-19 

socket server 37-8 
OPENARRAY, macro 13-19 



OpenDatabase, metodo 24-19, 
24-20 

OpenSession, metodo 24-30 
operatori 

assegnazione 13-7 
bitwise 

integer con segno A-5 
operazioni batch 24-8 - 24-9, 
24-50 - 24-55 
aggiornamento dati 24-52 
aggiornamento dei 

dati 24-52 
aggiunta di dati 24-52 
cancellazione di record 24-53 
copia di dataset 24-52 
database differenti 24-52 
esecuzione 24-54 
gestione degli errori 24-54 - 
24-55 

impostazione 24-50 - 24-51 

mappatura dei tipi di 
dati 24-53-24-54 

modalita 24-8, 24-51 
operazioni raster 50-7 
Options, proprieta 9-18 

grigliedati 19-26 

griglie decisionali 20-13 

provider 28-5-28-6 

TSQLClientDataSet 27-18 
opzione del compilatore 

allineamento A-6 
opzioni 

reciprocamente 
esclusive 8-48 
opzioni del compilatore 7-3 
opzioni del linker 

package 15-13 
opzioni di progetto 7-3 

predefinite 7-3 
ora A-12 

internazionalizzazione 16-10 
ora, formati A-12 
Oracle, driver 

distribuzione 17-9 
Oracle, tabelle 24-13 
Oracle8 

limiti sulla creazione di 
tabelle 22-41 
orario A-12 
ORB 31-1, 31-6 

inizializzazione 31-4 

ORB_init 31-8 
ORDER BY, clausola 22-27 
ordinamento 16-10 

dataset client 27-8 



discendente 27-9 
ore 

inserimento 9-13 
Orientation, proprieta 

griglie dati 19-31 

track bar 9-6 
Origin, proprieta 10-29, 23-13 
osagent 31-2, 31-3 
ottimizzazione delle risorse di 

sistema 45-4 
out-of -process, server 38-7 

ASP 42-7 
output, parametri 22-53, 27-29 
overload di procedure 

registrate 24-13 
Overload, proprieta 24-13 
Owner, proprieta 45-17 
owner-draw, controlli 4-21, 6-12 

caselle di riepilogo 9-11,9-12 

dichiarazione 6-13 

disegno 6-15, 6-16 

domensionamento 6-15 
OwnerDraw, proprieta 6-13 

P 

pacchetti dati 30-4 
a sola lettura 28-5 
acquisizione 27-28 - 27-29, 
28-8 

aggiornamento dei record 

aggiornati 28-6 
controllo di campi 28-5 
conversione in documenti 

XML 30-1 - 30-8 
copia 27-15-27-16 
editing 28-8 

garanzia di record unici 28-5 
including field 

properties 28-6 
informazioni definite 

dall'applicazione 27-16, 

28-7 

limitazione delle modifiche 

del client 28-5 
mappatura a documenti 

XML 30-2 
XML 29-31,29-33,29-36 
modifica 29-37 
recupero 29-36-29-37 
pacchetti delta 28-8, 28-9 
editing 28-8, 28-9 - 28-10 
valutazione degli 

aggiornamenti 28-11 
XML 29-36, 29-37 - 29-38 
package 15-1 - 15-16, 52-20 
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assegnazione del nome 15-10 
caricate dinamicamente 15-4 
compilazione 15-11 - 15-14 
componenti 15-9, 52-20 
creazione 7-10, 15-7 - 15-13 
custom 15-5 

di esecuzione 15-3 - 15-5, 
15-8 

di progettazione 15-5 - 15-7 
direttive al 

compilatore 15-12 
distribuzione ad altri 

sviluppatori 15-14 
distribuzione di 

applicazioni 15-14 
DLL 15-1, 15-2, 15-12 
editing 15-8 

elenco Contains 15-7, 15-9, 

15-11, 52-20 
elenco Requires 15-7, 15-9, 

15-10, 52-20 
esecuzione 15-1 
estensioni del nome del 

file 15-1,15-8,15-13 
file di opzioni del 

progetto 15-9 
filesorgenti 15-2,15-8 
impostazioni 

predefinite 15-8 
installazione 15-6 - 15-7 
internazionalizzazione 16-11 

, 16-13 
mancanti 52-20 
opzione per sola 

progettazione 15-8 
opzioni 15-8 
opzioni del linker 15-13 
packaging debole 15-12 
progettazione 15-1 
raccolte 15-15 
riferimenti duplicati 15-11 
uso in applicazioni 15-3 - 

15-5 
utilizzo 7-11 
Package Collection Editor 15-15 
package di esecuzione 15-1, 

15-3 - 15-5 
package di progettazione 15-1, 

15-5 - 15-7 
package, argomento 13-30 
package, file 17-3 
packaging debole 15-12 
PacketRecords, proprieta 14-29, 

24-34, 27-28 
page dispatcher 34-10, 34-37 



Page, controlli 9-16 
PageSize, proprieta 9-6 
pagina, controlli 

aggiunta di pagine 9-16 
pagina, moduli 34-2, 34-4 - 34-5 
pagine di codice 16-3 
pagine di login 

WebSnap 34-28-34-30 
pagine di proprieta 43-14 - 
43-16 

aggiornamento 43-15 
aggiornamento dei controlli 

ActiveX 43-16 
aggiunta di controlli 43-15 - 

43-16 

associazione a proprieta di 
un controllo ActiveX 43-15 

controlli ActiveX 40-7, 43-3, 
43-16 

controlli importati 40-5 
creazione 43-14-43-16 

paint boxes 9-20 

Paint, metodo 50-6, 54-9, 54-10 

paintbox 5-7 

PaintRequest, metodo 51-14 
PaletteChanged, metodo 50-6, 
51-15 

PanelHeight, proprieta 19-31 
panels 

beveled 9-20 
Panels, proprieta 9-17 
PanelWidth, proprieta 19-31 
pannelli 9-7 

aggiunta di pulsanti di scelta 
rapida 8-47 

associazione alia parte alta 
delleschede 8-47 

pulsanti di scelta rapida 9-8 

ridimensionamento 9-7 
pannelli rialzati 9-20 
Paradox, tabelle 24-3, 24-5 

accesso ai dati 24-9 

aggiunta di record 22-20 

assegnazione nuovo 
nome 24-8 

DatabaseName 24-3 

directory 24-25 

protezione con 
password 24-22-24-24 

recupero di indici 22-28 

transazioni locali 24-33 
ParamBindMode, 
proprieta 24-12 
ParamByName, metodo 

procedure registrate 22-55 



query 22-48 
ParamCheck, proprieta 22-47, 

26-12 
Parameter collection, 
editor 22-47, 22-54 
Parameters, proprieta 25-20 
TADOCommand 25-20 
TADOQuery 22-47 
TADOStoredProc 22-53 
parametri 

classi come 46-11 
da broker XML 29-37 
dataset client 27-29 - 27-31 

filtraggio di record 27-31 
eventi del mouse 10-25, 
10-26 

gestori di evento 48-7, 48-8, 
48-9 

impostazione delle 

proprieta 47-7 
proprieta dell'array 47-9 
input 22-53 
input/output 22-53 
interfacce duali 41-16 
marcatori HTML 33-14 
messaggi 51-4, 51-5, 51-7, 

51-10 
modalita di 

inglobameento 24-12 
output 22-53,27-29 
passaggio per 

riferimento 48-3 
risultato 22-53 
TXMLTransformClient 30-10 
parametri della transazione 

livello di isolamento 21-11 
parametri di connessione 24-15 
ADO 25-4 
dbExpress 26-4,26-5 
informazioni di login 21-5, 

25-4 

parametri facoltativi 28-7 

ParamName, proprieta 29-40 

Params, proprieta 

dataset client 27-29, 27-30 
procedure registrate 22-53 
query 22-48 
TDatabase 24-15 
TSQLConnection 26-4 
XML, broker 29-37 

ParamType, proprieta 22-48, 
22-54 

Param Values, proprieta 22-48 
Parent, proprieta 45-17 
ParentColumn, proprieta 19-26 
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ParentConnection, 

proprieta 29-30 
ParentShowHint, proprieta 9-17 
parola riservata read 54-5 
parole chiave 52-5 
protected 48-5 
parole chiave, help basati 

su 7-33 
parte query (URL) 32-4 
pascalimplementation, 

argomento 13-31 
passthrough SQL 24-32 
password 

connessioni implicite e 24-14 
tabelle dBASE 24-22 - 24-24 
tabelle Paradox 24-22 - 24-24 
PasteFromClipboard, 
metodo 6-10 
controlli memo data- 
aware 19-10 
grafici 19-10 
Pathlnfo, proprieta 33-6 
.pee, file 15-15 

Pen, proprieta 10-4, 10-6, 50-3 
penne 10-6, 54-6 

cambio 54-8 

colori 10-6 

impostazioni 
predefinite 10-6 

modalita di disegno 10-30 

ottenimento della 
posizione 10-8 

pennelli 10-5 

posizione, 
impostazione 10-8, 10-26 

spessore 10-6 

stile 10-7 
pennelli 10-8 - 10-10, 54-6 

cambio 54-8 

colori 10-9 

proprieta delle bitmap 10-10 

stili 10-9 
PenPos, proprieta 10-4, 10-8 
penwin.dll 15-13 
per utente, sottoscrizioni 40-17 
percorsi (URL) 32-4 
Perform, metodo 51-9 
permessi sui file 

Linux 14-15 
perror, funzione A-ll 
persistenti, sottoscrizioni 40-17 
personalizzazione dei 

componenti 47-1 
PickList, proprieta 19-22, 19-23 
Picture property 



in frame 8-16 
picture, oggetti 10-3 
Picture, proprieta 9-20, 10-18 
Pie, metodo 10-5 
pivot decisionali 20-10 

comportamenti in 
esecuzione 20-19 

orientamento 20-10 

proprieta 20-10 

pulsanti di dimensione 20-10 
pixel 

lettura e impostazione 10-10 
Pixel, proprieta 10-4, 50-3 
Pixels, proprieta 10-5, 10-10 
pmCopy, costante 10-30 
pmNotXor, costante 10-30 
poligoni 10-12 

disegno 10-12 
Polygon, metodo 10-5, 10-12 
PolyLine, metodo 10-5, 10-11 
PopupMenu, componente 8-33 
PopupMenu, proprieta 6-11 
Port, proprieta 37-7 

TSocketConnection 29-25 
porte 37-5 

connessioni multiple 37-5 

servizi e 37-2 

socket client 37-6,37-7 

socket server 37-7 
porting del codice 14-17 - 14-21 
porting di applicazioni 

in Linux 14-2-14-21 
Position, proprieta 9-6, 9-17 
position-independent code 

(PIC) 14-9,14-20 
Post, metodo 22-21 

Edite 22-19 
PostMessage, metodo 51-10 
#pragma, package 52-20 
Precision, proprieta 

campi 23-13 

parametri 22-48, 22-54, 22-55 
predefinita 

classe antenato 46-4 
predefinite 

opzioni di progetto 7-3 
predefiniti 
gestori 

eventi 48-9 
ridefinizione 48-9 
parametri 13-22 
valori 19-11 
valori della proprieta 
cambio 53-3, 53-4 
valori delle proprieta 47-7 



specifica 47-12-47-13 
predefinito 
gestori 

messaggio 51-4 
Prepared, proprieta 

dataset unidirezionali 26-9 
procedure registrate 22-56 
query 22-50 
pressione tasti, eventi 48-3, 48-9 
Preview, pagina 34-2 
primari, indici 

operazioni batch e 24-52, 
24-53 

PRIMARY KEY, vincolo 28-14 
principale, scheda 8-3 
Prior, metodo 22-7 
priorita 

usodi thread 11-1, 11-3 
Priority, proprieta 11-3 
private, proprieta 47-5 
PrivateDir, proprieta 24-25 
ProblemCount, proprieta 24-54 
ProblemTableName, 

proprieta 24-54, 24-55 
procedure 

assegnazione dei nomi 49-2 
procedure registrate 18-5,22-25, 
22-52 - 22-57 
basate su BDE 24-2, 24-12 - 
24-13 
inglobamento di 
parametri 24-12 
caricate in 

sovrapposizione 24-13 
creazione 26-11 
dbExpress 26-8 
elenco 21-15 
esecuzione 22-56 
parametri 22-53-22-56 
da dataset client 27-31 
in esecuzione 22-55 - 
22-56 

in progettazione 22-54- 
22-55 

proprieta 22-54-22-55 
preparazione 22-56 
specifica del database 22-52 
ProcedureName, 
proprieta 22-52 
processi lenti 

uso di thread 11-1 
processi parallelli 

thread 11-1 
produttori di contenuti 33-4, 
33-14 



In dice 1-35 



gestione di eventi 33-16, 

33-17, 33-18 
produttori di pagine 33-14 - 
33-18, 34-2, 34-4, 34-7, B-l 
concatenamento 33-17 
Content, metodo 33-15 
ContentFromStream, 

metodo 33-15 
ContentFromString, 

metodo 33-15 
conversione modelli 33-16 
data-aware 29-39 - 29-43, 

33-19 

gestione di eventi 33-16, 

33-17, 33-18 
modelli 34-4 
tipi 34-11 
produttori di tabelle 33-19 - 
33-21 

profondita dei colori 17-13 
programmazione 17-15 
progetti 

aggiunta di schede 8-1 - 8-4 
progetti, file 

distribuzione 2-5 
modifica 2-2 
progetto, modelli 7-27 
progetto, wizard 58-4 
programmazione di modelli 7-3 
programmazione object- 
oriented 46-1 - 46-11 
dichiarazione 

metodi 46-10 
dichiarazioni 46-3, 46-11 
classi 46-5, 46-7, 46-8 
Project Manager 8-3 
Project Options, finestra di 

dialogo 7-3 
Project Updates, finestra di 

dialogo 31-10 
PROP_P AGE, macro 43-16 

property, parola chiave 13-27 

Property Page, wizard 43-14 - 
43-15 

PROPERTYPAGEJMPL 

macro 43-15 
Proportional, proprieta 10-3 
proprieta 3-2, 47-1 - 47-14 

a sola lettura 46-7, 46-8, 47-7, 
56-3 

a sola scrittura 47-7 
accesso 47-5-47-7 
aggiornamento 45-7 
aggiunta a controlli 
ActiveX 43-9-43-11 



aggiunta a interfacce 41-10 
array 47-3, 47-8, 47-9 
cambio 52-7-52-13,53-3, 
53-4 

caricamento 47-14 
COM 38-3, 39-9 

Write By Reference 39-9 
come classi 47-2 
componenti wrapper 57-4 
dichiarazione 47-3, 47-3 - 

47-7, 47-8, 47-13, 48-8, 54-4 
tipi definiti 
dall'utente 54-4 
editing 

come testo 52-9 
ereditate 47-3, 54-3, 55-3 
eventi e 48-1,48-2 
finestre di dialogo 

comuni 57-2 
impostazione 5-2 - 5-3 
interfacce COM 39-9 
lettura di valori 52-9 
nodefault 47-8 
panoramica 45-6 
preparazione della 

guida 52-4 
published 55-3 
read e write 47-5 
registrazione 47-13 
registrazione e caricamento 

di non pubblicate 47-14 - 

47-16 

registrazione interna dei 

dati 47-4, 47-7 
ridichiarazione 47-12, 48-5 
scrittura di valori 47-7, 52-9 
specifica di valori 47-12, 

52-10 

subcomponent 47-10 
tabelle HTML 33-20 
tipi 47-2, 47-9, 52-9, 54-4 
valori predefiniti 47-7, 47-12 
- 47-13 
ridefinizione 53-3, 53-4 
visualizzazione 52-9 
proprieta array 13-24 
proprieta, controlli memo e rich 

edit 9-3 
protected 

direttiva 48-5 
eventi 48-5 

parola chiave 47-3, 48-5 
sezione delle classi 46-7 
protocolli 



componenti 
connessione 29-9 - 29-12, 
29-24 

connessioni di rete 24-16 
Internet 32-3 
scelta 29-9 - 29-12 
protocollo 

Internet 37-1 
provider 28-14,29-3 
applicazione degli 

aggiornamenti 28-4, 28-8, 

28-11, 28-12 
associazione a dataset 28-2 
associazione con documenti 

XML 28-2,30-8 
dataset client e 27-26 - 27-34 
esterni 18-11, 27-20, 27-26, 

28-2 

eventi generati dal 

client 28-13 
fornitura dati a documenti 

XML 30-9-30-11 
gestione errori 28-12 
interni 27-20, 27-26, 28-1 
locali 27-27, 28-3 
remoti 27-27,28-3,29-6 
utiizzo di oggetti 

update 24-11 
valutazione degli 

aggiornamenti 28-11 
vincoli sui dati 28-13 
XML 30-8 - 30-9 
Provider, proprieta 25-4 
ProviderFlags, proprieta 28-5, 
28-11 

ProviderName, proprieta 18-13, 

27-27, 28-3, 29-23, 29-37, 30-9 
proxy 38-7,38-8 

interfacce di evento 40-6 

oggetti transazionali 44-3 
public 

parola chiave 48-5 

proprieta 47-12 

sezione delle classi 46-7 
published 47-3 

direttiva 47-3,57-4 

parola chiave 48-5 

proprieta 47-12,47-13 
esempio 54-3, 55-3 

sezione delle classi 46-8 

published, parola 

chiave 13-28 
pulsanti 9-7-9-9 

aggiunta alle barre 
strumenti 8-47 - 8-49, 8-50 



1-36 Guida alia programmazione 



assegnazione di simboli 8-47 
barre strumenti e 8-45 
disattivazone sulle barre 

strumenti 8-50 
navigatore 19-31 
pulsanti del mouse 10-25 
clic 10-26 

eventi di spostamento mouse 

e 10-27 
pulsanti di opzione 9-9, 19-2 
data-aware 19-15 
raggruppamento 9-14 
selezione 19-15 
pulsanti di scelta rapida 9-8 
aggiunta alle barre 

strumenti 8-47-8-49 
assegnazione di simboli 8-47 
centratura 8-47 
gestori di evento 10-14 
modi operativi 8-47 
per strumenti di 

disegno 10-14 
raggruppamento 8-48 - 8-49 
stato iniziale, 

impostazione 8-48 
utilizzo come 

commutatori 8-48 
pulsanti strumento 8-50 
a capo 8-50 

aggiunta di immagini 8-50 
disattivazone 8-50 
raggruppamento / 

separazione 8-50 
richiamo della guida 8-52 
stato iniziale, 

impostazione 8-50 
su piu righe 8-50 
utilizzo come 

commutatori 8-51 
puntatori 
classi 46-11 

conversione in integer A-5 

dereferenziati 13-7 

gestione delle eccezioni 12-5 

implicazioni nella VCL 13-6 

NULL A-8 

tipi integer A-5 

valori predefiniti delle 
proprieta 47-12 
puntatori a classi 46-11 
puntatori ad interfacce 38-5 
puntatori di trascinamento 6-2 
punti terminali 

connessioni socket 37-6 
puntini (...) 



pulsanti nelle griglie 19-23 
punto di aggancio 6-6 
putenv, funzione A-ll 
PVCS Version Manager 2-5 

Q 

QApplication_postEvent, 

metodo 51-16 
QCustomEvent_create, 

funzione 51-16 
QEvent 51-13 
QKeyEvent 51-13 
QMouseEvent 51-13 
QReport, pagina (Component 

palette) 5-8 
Qt widget 

creazione 14-13 
Qt, eventi 

messaggi 51-15 
quadrati, disegno 54-10 
query 22-25, 22-43 - 22-52 
applicazioni Web 33-21 
basate su BDE 24-2, 24-9 - 
24-12 
concorrenti 24-18 
set risultato live 24-10 - 
24-11 

cursor bidirezionali 22-51 
cursor unidirezionali 22-51 
esecuzione 22-50-22-51 
eterogenee 24-9-24-10 
filtraggioe 22-13 
oggetti update 24-49 - 24-50 
ottimizzazione 22-50, 22-51 
parametri 22-46 - 22-49 

con nome 22-46 

da dataset client 27-31 

impostazione in 
esecuzione 22-48 

impostazione in 
progettazione 22-47 

inglobamento 22-47 

proprieta 22-47-22-48 

relazioni master/ 
detail 22-49-22-50 

senza nome 22-46 
parametrizzate 22-45 
preparazione 22-50 
relazioni master/ 

detail 22-49 - 22-50 
set risultato 22-51 
specifica 22-44-22-46,26-6- 
26-7 

specifica del database 22-44 
tabelle HTML 33-21 



Query Builder 22-46 
query decisionali, 
definizione 20-6 
query eterogenee 24-9 - 24-10 

Local SQL 24-9 
query parametrizzate 22-45, 
22-46 - 22-49 
creazione 

in esecuzione 22-48 
in progettazione 22-47 
Query, proprieta 

oggetti aggiornamento 24-49 
Querylnterface, metodo 38-4 
aggregazione 38-9 

R 

raccolte di package, file 15-15 
raggruppamento di 

componenti 9-14-9-16 
RaiseException, funzione 12-13 
RC,file 8-45 
RDBMS 18-3,29-1 
RDSConnection, 

proprieta 25-17 
Read, metodo 

TFileStream 4-2 
read, metodo 47-7 
read, parola riservata 47-9 
ReadBuffer, metodo 
TFileStream 4-2 
ReadCommitted 21-10 
README 17-17 
README, documento 17-17 
ReadOnly, proprieta 9-3, 56-3, 

56-9, 56-10 
campi 23-13 

controlli data-aware 19-6 

controlli memo data- 
aware 19-9 

controlli rich edit data- 
aware 19-10 

griglie dati 19-22, 19-28 

tabelle 22-40 
ReaLtipo 13-24 
Real48,tipo 13-24 
realloc, funzione A-ll 
ReasonString, proprieta 33-12 
rebar 8-45,8-51 
ReceiveBuf, metodo 37-8 
Receiveln, metodo 37-8 
RecNo, proprieta 

dataset client 27-2 
Reconcile, metodo 14-29, 24-34 
record 

acquisizione 27-28 - 27-29 



In dice 1-37 



aggiornamento 19-7, 22-22 - 
22-23, 24-8, 24-52, 27-33, 
28-8, 29-37-29-38 
da documenti XML 30-10 

- 30-11 
dataset client 27-21 - 

27-26 
identificazione di 

tabelle 28-12 
multiple 28-6 
operazioni batch 24-8 
pacchetti delta 28-8, 28-9 
query e 24-11 
valutazione degli 
aggiornamenti 28-11 
aggiunta 22-19-22-20, 

22-23, 24-8, 24-52 
cancellazione 22-20 - 22-21, 
22-42 - 22-43, 24-8, 24-53 
operazioni batch 24-8 
conferma 22-21-22-22 
alia chiusura del 
dataset 22-22 
contrassegno 22-9 - 22-11 
copia 24-8,24-52 

operazioni batch 24-8 
criteri di ricerca 22-11,22-12 
filtraggio 22-13-22-16 
inoltro 19-6 

grigliedati 19-28 
iterazione tra 22-8 
operazioni 24-8 
operazioni batch 24-8, 24-52, 
24-53 

ordinamento 22-27 - 22-29 
prelievo 26-8-26-9 

asincrono 25-11-25-12 
ricerca 22-11-22-13,22-29- 

22-31 
riconciliazione degli 

aggiornamenti 27-25 
ripetizione della 

ricerca 22-31 
sincronizzazione del 

corrente 22-43 
spostamento tra 19-31, 22-5 - 

22-9, 22-17 
Type Library editor 39-11, 

39-18 

visualizzazione 19-30 
RecordCount, proprieta 

TBatchMove 24-54 
RecordSet, proprieta 25-20 
RecordsetState, proprieta 25-10 



RecordStatus, proprieta 25-12, 
25-14 

Rectangle, metodo 10-5, 10-12, 
50-3 

Refresh, metodo 19-7, 27-33 
RefreshLookupList, 

proprieta 23-10 
RefreshRecord, metodo 27-33, 

28-4 
register 

oggetti e A-5 
Register, metodo 10-3 
Register, procedura 52-2 
RegisterComponents, 

funzione 45-14 
RegisterComponents, 

procedura 15-6, 52-2 
RegisterConversionType, 

funzione 4-28,4-29 
RegisterHelpViewer 7-38 
RegisterNonActiveX, 

procedura 43-3 
RegisterPooled, flag 29-9 
RegisterPropertyEditor, 

funzione 52-12 
RegisterTypeLib, 

funczione 38-19 
Register Viewer, funzione 7-34 
registrazione 

Active Server Objects 42-8 
componenti 45-14, 45-15 
controlli ActiveX 43-16 - 
43-17 

editor di componenti 52-19 
editor di proprieta 52-12 - 
52-13 

famiglie di conversione 4-28 
interfacce CORBA 31-13 
oggetti COM 41-17-41-18 
registrazione di oggetti 

Help 7-34 
registro dei tipi remotable 36-5, 
36-15 

registro delle chiamate 36-3, 
36-13 
creazione di classi 
richiamabili 36-13 
registro delle modifiche 27-5, 
27-21, 27-36 
salvataggio delle 
modifiche 27-7 
registro modifiche 
annullamento delle 
modifiche 27-6 
Registry 16-10 



regole di gestione 29-2, 29-13 
ASP 42-1 

oggetti transazionali 44-2 
REGSERV32.EXE 17-5 
relazionali, database 18-1 
relazioni uno-a-molti 22-37, 

26-12 
Release 7-31 
Release, metodo 38-4 

TCriticalSection 11-8 
remotable, classi 36-4, 36-7 - 

36-10 

eccezioni 36-15 - 36-16 
esempio 36-9 - 36-10 
gestione della durata 36-8 
native 36-8 
registrazione 36-5 
Remote Data Module, 
wizard 29-14-29-15 
remote data modules 7-25 
Remote Database Management 

system 18-3 
remote, connessioni 
apertura 37-7 
interruzione 37-8 
multiple 37-5 
REMOTEDATAMODULEJMP 

L, macro 29-5 
RemoteHost, proprieta 37-6 
RemotePort, proprieta 37-6 
RemoteServer, proprieta 27-27, 
29-23, 29-28, 29-34, 29-36, 30-9 
remoti, server di database 18-3 
RemoveAllPasswords, 

metodo 24-23 
RemovePassword, 

metodo 24-23 
RenameFile, funzione 4-9, 4-10 
repainting controls 54-8 
RepeatableRead 21-10 
reperimento dati 

incrementale 27-28, 29-20 
report 18-17 
Repository 

Vedere Object Repository 
Request for Comment (RFC), 

documenti 32-3 
RequestLive, proprieta 24-10 
RequestRecords, metodo 29-37 
Requires, elenco (package) 15-7, 

15-9, 15-10, 52-20 
.res, file 45-16 
ResetEvent, metodo 11-11 
resizing controls 17-13 



1-38 Guida alia programmazione 



ResolveToDataSet, 

proprieta 28-4 
Resource DLLs 

alternanza dinamica 16-12 

wizard 16-11 
resourcestring, macro 13-22 
RestoreDefaults, metodo 19-24 
restrizioni A-l 
Result, parametro 51-7 
Resume, metodo 11-12 
reti 

connessione a 
database 24-16 

strato di comunicazione 31-2 
reti locali 31-3 
rettangoli 

disegno 10-11,54-10 
rettangoli arrotondati 10-12 
rettangoli di contorno 10-12 
Return Value, proprieta 11-10 
RevertRecord, metodo 14-29, 

24-34, 27-6 
RFC, documenti 32-3 
ricerca di file A-7 
ricerca incrementale 19-11 
ricerche basate su indice 22-29 - 
22-31 

ricerche basate su indici 22-12, 
22-13 

rich edit, controlli 9-3 

rich text, controlli 6-7, 19-10 

richiamabili, interfacce 36-2 - 

36-10 
richieste 

adapter 34-38 

immagini 34-40 

indirizzamento 34-36 
richieste dei client 33-9 
richieste del client 32-5 - 32-7 
ridefinizione 

metodi 51-4, 51-5, 55-13 

metodi virtuali 13-11 
ridimensionamento dei 
controlli 55-4 

grafici 50-7 
ridimensionamento di 

controlli 9-7 
riferimenti 

a schede 8-3 

C++ e Object Pascal 13-6 
riferimenti circolari 8-4 
riferimenti sicuri 44-27 
riferimento a oggetto 13-6 
riferimento, campi 

visualizzazione 19-26 



righe 9-17 

griglie decisionali 20-12 
rilascio dei pulsanti del 

mouse 10-26 
rilocabile, codice 14-20 
risoluzione 28-1, 29-4 
risorse 45-8, 50-1 

assegnazione dei nomi 52-4 

isolamento 16-10 

localizzazione 16-11, 16-13 

memorizzazione in 
cache 50-2 

sistema, ottimizzazione 45-4 

stringhe 16-11 
risorse, file 8-45 

caricamento 8-45 
risposte 

adapter 34-38 

azioni 34-39 

immagini 34-40 
risposte di azioni 34-39 
risposte HTTP 

azioni 34-39 
risultato, parametri 22-53 
ritenzione degli 

annullamenti 25-6 
ritenzione delle modifiche 25-6 
ritracciamento dei 

controlli 54-10, 55-4, 55-5 
ritracciamento di immagini 50-7 
Rollback, metodo 21-9 
RollbackTrans, metodo 21-9 
root, directory 

Linux 14-16 
RoundRect, metodo 10-5, 10-12 
routine 

terminate con null 4-25 - 
4-26 

routine globali 4-1 
Row Attributes, proprieta 33-20 
RowCount, proprieta 19-14, 
19-31 

RowHeights, proprieta 6-15, 
9-18 

RowRequest, metodo 28-4 

Rows, proprieta 9-18 

RowsAffected, proprieta 22-51 

RPC 38-9 

RTTI 46-8 

C++ e Object Pascal 13-23 
interfacce richiamabili 36-2 

s 

safe array 39-13 
safe, puntatori 



gestione delle eccezioni 12-5 
SafeArray 39-13 
SafeRef, metodo 44-27 
Samples, pagina (Component 

palette) 5-8,5-9 
Save as Template, comando 
(Menu designer) 8-40, 8-43 
Save Attributes, comando 23-14 
Save Template, finestra di 

dialogo 8-43 
SaveConfigFile, metodo 24-26 
SavePoint, proprieta 27-6 
SaveToFile, metodo 10-21 

datasetADO 25-15 

dataset client 18-10, 27-37 

elementi grafici 50-4 

stringhe 4-16 
SaveToStream, metodo 

dataset client 27-37 
scalabilita 18-11 
ScanLine, proprieta 

esempio con bitmap 10-19 
scheda, file 14-2 
scheda, wizard 58-4 
schede 8-1 

aggiunta a progetti 8-1 - 8-4 

aggiunta di campi 10-27 - 
10-29 

aggiunta di riferimenti a 

unit 8-3 
collegamento 8-3 
come componenti 57-1 
condivisione di gestori di 

evento 10-16 
creazione in esecuzione 8-6 
drill down 19-16 
gestione della memoria 8-5 
interrogazione di proprieta 

esempio 8-9 
modali 8-5 
non modali 8-5, 8-7 
ottenimento di dati 8-9 - 

8-12 

passaggio di argomenti a 8-8 

principale 8-3 

referenziazione 8-3 

sincronizzazione dei 
dati 19-4 

tabelle master/detail 19-16 

uso di variabili locali per 
creare 8-7 

variabile globale per 8-6 

visualizzazione 8-6 
schede, linking 8-3 
schermo 



Indice 1-39 



aggiornamento 10-2 

risoluzione 17-13 

programmazione 17-13 
ScktSrvr.exe 29-10, 29-14, 29-25 
SCM 7-5 

scorciatoie di tastiera 

aggiunta a menu 8-36 - 8-37 
Screen, variabile 8-2, 16-9 
script 

active 34-34 

generazione in 
WebSnap 34-35 

modifica e 
visualizzazione 34-35 

URL 32-4 
script di login 21-4-21-6 
script per Web 34-8 
script, oggetti 34-35 
scripting 34-8 

scripting lato server 34-8, 34-33 
- 34-36, B-l - B-39 
esempi JScript B-19 - B-39 
oggetti globali B-14 - B-19 
tipi di oggetti B-2-B-14 

ScrollBars, proprieta 6-8, 9-18 
controlli memo data- 
aware 19-9 

SDI, applicazioni 7-1 - 7-3 

Sections, proprieta 9-16 

Seek, metodo 

datasetADO 22-29 

segmenti consecutivi di 
linee 10-11 

segnalazione di eventi 11-10 

segnali 

Linux 14-15 

risposta (CLX) 51-11 - 51-12 
segnalibri 22-9-22-11 

filtraggio di record 25-11 
segni diacritici 16-10 
Select Menu, comando (Menu 

designer) 8-40,8-41 
Select Menu, finestra di 

dialogo 8-41 
SELECT, istruzioni 22-44 
SelectAll, metodo 9-4 
SelectCell, metodo 55-14, 56-4 
Selection, proprieta 9-18 
SelectKeyword 7-34 
SelEnd, proprieta 9-6 
selettori 

Help 7-35 
Selezione 34-11 
SelLength, proprieta 6-9, 9-3 
SelStart, proprieta 6-9, 9-3, 9-6 



SelText, proprieta 6-9, 9-3 
SendBuf, metodo 37-8 
Sender parameter 5-5 
Sender, parametro 

esempio 10-7 
Sendln, metodo 37-8 
SendMessage, metodo 51-10 
SendStream, metodo 37-8 
sensibilita maiuscole/ minuscole 

identificatori esterni e A-3 

Linux 14-14 

soppressione A-3 
separatori 

eventi draw-item 6-16 
separatori dei notebook 9-15 
sequenza di collazione A-2 
sequenza di ordinamento 

TSQLTable 26-7 
sequenze di escape 

file sorgenti A-7 
server 

Internet 32-1 - 32-12 

Web application 
debugger 34-9 
server di applicazioni 

basati su COM 29-17, 29-22 

basato su COM 29-5 
server di database 

connessione 18-8 - 18-9 

vincoli 23-22, 23-23, 28-13 
server in-process 38-7 

ActiveX 38-14 

ASP 42-7 

MTS 44-2 
server remoti 24-9, 38-7 

accesso non autorizzato 21-4 

maintenimento delle 
connessioni 24-19 
server Web 29-32,42-7 

richieste del client e 32-6 
server Web, applicazioni 

ASP 42-1 
server, applicazioni 

CORBA 31-2, 31-4 - 31-14 

registrazione 31-13 - 31-14 
OAD 31-4 
server, socket 

oggetti socket 37-7 
ServerGUID, proprieta 29-24 
ServerName, proprieta 29-24 
Servers, pagina (Component 

palette) 5-8,5-9 
Service Control Manager 7-5, 
7-9 

Service Start name 7-9 



servizi 7-4 - 7-9 

API Tools 58-2, 58-8 - 58-14 
codice di esempio 7-5, 7-7 
CORBA 31-1 
directory 31-2, 31-3 
disinstallazione 7-5 
esempio 7-7 
implementazione 37-1 - 

37-2, 37-7 
installazione 7-5 
Name, proprieta 7-9 
portee 37-2 
richiesta 37-6 
server di rete 37-1 
servizio per le sessioni 34-28 
servizio, thread di 7-7 
Session, variabile 24-3, 24-17 
sessioni 24-17-24-31 
apertura di 

connessioni 24-20 
applicazioni multi- 
thread 24-13,24-29-24-31 
applicazioni Web 33-18 
assegnazione dei nomi 33-19 
assegnazione del nome 24-29 
attivazione 24-18 - 24-19 
chiusura 24-19 
chiusura delle 

connessioni 24-20 
connessione predefinita, 

proprieta 24-19 
connessioni implicite a 

database 24-13 
creazione 24-28-24-29, 

24-30 

database associati 24-21 - 
24-22 

database e 24-13-24-14 
datasete 24-3-24-4 
gestione alias 24-25 
gestione delle 

connessioni 24-20 - 24-22 
metodi 24-14 

multiple 24-13,24-28,24-29- 

24-31 
ottenimento di 

informazioni 24-27 - 24-28 
password 24-22 
predefinite 24-3, 24-13, 24-17 

- 24-18 
riavvio 24-19 
statoattuale 24-18 
SessionName, proprieta 24-3, 

24-4, 24-13, 24-29, 24-30, 33-19 
sessions service 34-11,34-27 
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Sessions, proprieta 24-30 
Sessions, variabile 24-18, 24-30 
set 47-2 

set di caratteri 4-21, 16-2, 16-2 - 
16-4, A-2, A-4 
ANSI 16-3 

conversioni multibyte 16-3 

costanti A-7 

estesi A-2 

mappatura A-4 

multibyte 16-3 

OEM 16-3 

ordinamenti 

internazionali 16-10 
predefiniti 16-2 
verifica A-8 
set di tab 9-15 

SetAbort, metodo 44-5, 44-9, 
44-14 

SetBrushStyle, metodo 10-9 
SetComplete, metodo 29-18, 

44-5, 44-9, 44-14 
SetData, metodo 23-18 
SetEvent, metodo 11-10 
SetFields, metodo 22-22 
SetFloat Value, metodo 52-9 
SetKey, metodo 22-29 

EditKeye 22-31 
SetMethodValue, metodo 52-9 
SetOptionalParam, 

metodo 27-16 
SetOrdValue, metodo 52-9 
SetPenStyle, metodo 10-7 
SetProvider, metodo 27-27 
SetRange, metodo 22-34 
SetRangeEnd, metodo 22-33 

SetRange e 22-34 
SetRangeStart, metodo 22-32 

SetRange e 22-34 
SetSchemalnfo, metodo 26-13 
SetStr Value, metodo 52-9 
SetUnhandledExceptionFilter, 

funzione 12-7 
SetValue, metodo 52-9, 52-10 
sezioni critiche 11-8 

avvertenze sull'uso 11-8, 
11-9 
sfondi 16-10 
sfondi trasparenti 16-10 
sgancio di controlli 6-7 
Shape, proprieta 9-20 
shared object files Vedere .so, file 
Shared Property Manager 44-7 
-44-9 

esempio 44-7-44-9 



shell, script 

Linux 14-14 
Shift, stati 10-25 
ShortCut, proprieta 8-37 
Show, metodo 8-6, 8-8 
ShowAccelChar, proprieta 9-4 
ShowButtons, proprieta 9-13 
ShowColumnHeaders, 

proprieta 9-13 
ShowFocus, proprieta 19-31 
ShowHint, proprieta 9-17, 19-34 
ShowHintChanged, 

metodo 51-15 
Snowlines, proprieta 9-13 
ShowModal, metodo 8-6 
ShowRoot, proprieta 9-13 
ShutDown 7-30,7-31 
sicurezza 

applicazioni multi-tier 29-2 
connessioni SOAP 29-26 
connessioni Web 29-11, 
29-26 

database 18-4, 21-4 - 21-6, 

24-22 - 24-24 
DCOM 29-35 
moduli dati 

transazionali 29-7, 29-10 
oggetti transazionali 44-17 - 

44-18 

registrazione di connessioni 

socket 29-10 
tabelle locali 24-22 - 24-24 
sicurezza basata sul ruolo 44-17 
signal, funzione A-9 
Simple Object Access Protocol 

Vedi SOAP 
sincronizzatore multilettura a 

scrittura esclusiva 11-9 
sincronizzazione dei dati 

su piu schede 19-4 
sincronizzazione delle 

chiamate 44-21 - 44-22 
single document interface 7-1 - 
7-3 

single-tier, applicazioni 18-9, 
18-13 

basate su file 18-10 
sistemi di Guida 52-4 

file 52-5 

parole chiave 52-5 
pulsanti strumento 8-52 
Size, proprieta 
campi 23-13 

parametri 22-48, 22-54, 22-55 
sizeof, operatore 13-18, A-7 



skeleton 31-2,31-2-31-3,31-6- 
31-7 

delega 31-9 

marshaling 31-3 
Smart Agents 31-2,31-3 

ubicazione 31-3 
smistatore free-threaded 41-7 
.so, file 14-9, 14-15 
SOAP 36-1 

applicazioni multi-tier 29-11 

connessione a server di 
applicazioni 29-26 

connessioni 29-11,29-26 

moduli dati 29-6 

pacchetti di errore 36-15 

wizard di applicazioni 36-11 
SOAP Data Module 

wizard 29-16 - 29-17 
socket 37-1 - 37-11 

accettazione richieste del 
client 37-3 

assegnazione host 37-4 

descrizione 37-3 

fornitura di 
informazioni 37-4 

gestione degli errori 37-8 

gestione di eventi 37-8 - 
37-10 

implementazione di 
servizi 37-1 - 37-2, 37-7 

indirizzi di rete 37-3, 37-4 

lettura da 37-10 

lettura/ scrittura 37-10 - 
37-11 

scrittura su 37-10 
socket client 37-3, 37-6 - 37-7 

assegnazione host 37-4 

connessione a server 37-9 

gestione di eventi 37-9 

identificazione dei 
server 37-6 

messaggi di errore 37-8 

proprieta 37-6 

richiesta di servizi 37-6 
socket dispatcher, 

applicazione 29-14, 29-25 
socket server 37-7-37-8 

accettazione delle richieste 
del client 37-7, 37-9 

gestione di eventi 37-9 

messaggi di errore 37-8 

specifica 37-6 
socket, componenti 37-5 - 37-8 
socket, oggetti 37-6 

client 37-6 
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socket client 37-6 

socket server 37-7 
SoftShutDown 7-30 
sola lettura 

campi 19-6 

dataset, 
aggiornamento 18-11 

proprieta 46-7, 46-8, 47-7, 
56-3 

tabelle 22-40 
sola scrittura, proprieta 47-7 
sollevamento di eccezioni 12-13 
sorgenti dati 18-7, 19-3 - 19-5 

attivazione 19-4 

disattivazione 19-4 

eventi 19-4-19-5 
sorgenti decisionali 20-9 - 20-10 

eventi 20-9 

proprieta 20-9 
Sorted, proprieta 9-11, 19-12 
SortFieldNames, proprieta 26-7 
sottomenu 8-37 
SourceXmlDocument, 

proprieta 30-7 
SourceXmlFile, proprieta 30-6 
Spacing, proprieta 9-8 
SparseCols, proprieta 20-9 
SparseRows, proprieta 20-9 
specificatori di classe storage 

register A-5 
spezzate 10-10,10-11 

disegno 10-10 
spin edit, controlli 9-6 
SPX/IPX 24-16 
SQL 18-3,24-9 

esecuzione di comandi 21-11 
-21-12 

locale 24-9 

standard 28-13 

Decision Query editor 
e 20-7 
SQL Builder 22-46 
SQL Explorer 24-56, 29-3 

definizione dei set di 
attributi 23-14 
SQL Links 17-8,24-1 

distribuzione 17-9, 17-17 

driver 24-9, 24-16, 24-32 

file driver 17-9 

requisiti di licenza 17-17 
SQL Monitor 24-57 
SQL, dataset client 27-23 - 27-25 
SQL, istruzioni 

dataset decisionale 20-5 

esecuzione 26-9-26-11 



fornite dal client 27-34, 28-6 
generati dal provider 28-12 
generazione 

provider 28-4, 28-10 - 

28-11 
TSQLDataSet 26-9 
oggetti update and 24-42 - 

24-46 
parametri 21-12 
passthrough SQL 24-32 
SQL, passthrough 24-31 
SQL, proprieta 22-45 - 22-46 

cambio 22-50 
SQL, query 22-44 - 22-46, 44-13 
caricamento da file 22-46 
copia 22-46 

esecuzione 22-50-22-51 
modifica 22-45 
oggetti di 

aggiornamento 24-48 
ottimizzazione 22-51 
parametri 22-46-22-49, 
24-44 - 24-45 
impostazione in 

esecuzione 22-48 
impostazione in 

progettazione 22-47 
inglobamento 22-47 
relazioni master/ 
detail 22-49-22-50 
preparazione 22-50 
setrisultato 22-51 
SQL, server 

login a 18-4 
SQLConnection, proprieta 26-3, 
26-18 

SQLPASSTHRUMODE 24-32 
stampa 4-26 
stampanti A-3 

standard, componenti 5-7 - 5-9 
standard, eventi 48-4 

personalizzazione 48-6 
Standard, pagina (Component 

palette) 5-7 
StartTransaction, metodo 21-7 
State, proprieta 9-9 

colonne della griglia 19-17 

dataset 22-3,23-9 

griglie 19-17,19-20 
StatusCode, proprieta 33-12 
StatusFilter, proprieta 14-29, 

24-34, 25-12, 27-6, 27-21, 28-9 
StdConvs, unit 4-27, 4-28, 4-30 
Step, proprieta 9-17 
StepBy, metodo 9-17 



Steplt method 9-17 
StoredProcName, 
proprieta 22-52 
StrByteType 4-23 
stream 4-2 

copia di dati 4-3 

dimensioni 4-3 

lettura e scrittura dati 4-2 

posizione 4-3 

ricerca 4-3 

supporto di 
memorizzazione 4-3 
stream binari 

caratteri null e A-9 
stream di file 4-5-4-7 

apertura 4-6 

cambio della dimensione 4-4 

creazione 4-6 

eccezioni 4-2 

I/O su file 4-5-4-7 

ottenimento di un 
handle 4-10 

portabile 4-5 

segnale di fine stream 4-4 
strerror, funzione A-12 
Stretch, proprieta 19-10 
StretchDraw, metodo 10-5,50-3, 
50-7 

String List editor 

visualizzazione 19-11 
stringhe 4-21, 47-2, 47-8 
associazione a elementi 

grafici 6-14 
conversioni a 2 byte 16-3 
dichiarazione e 

inizializzazione 4-26 
dimensioni 6-9 
modelli HTML 33-15 
modifica permanente A-ll 
ordinamento 16-10 
posizione iniziale 6-9 
restituzione 47-9 
routine 

della libreria 

runtime 4-21 
differenze maiuscole / 

minuscole 4-22 
supporto dei caratteri 
multi-byte 4-23 
terminate con null 4-25 - 
4-26 

trasformazione 16-2, 16-8, 

16-10 
troncamento 16-3 
stringhe di risorse 13-21 
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Strings, proprieta 4-19 
StrNextChar, funzione 

Linux 14-18 
Structured Query Language 

vedi SQL 
strumenti di disegno 50-7, 54-6 

assegnazione come 
predefinito 8-48 

cambio 54-8 

controllodi 10-13 

gestione di piu strumenti in 
applicazioni 10-13 

modifica 10-14 
strumenti di traduzione 16-1 
strutture A-6 

stub 31-2 - 31-3, 31-6 - 31-7, 
31-15-31-16 

COM 38-8 

marshaling 31-3 

oggetti transazionali 44-3 

variabili globali 31-16 
Style, proprieta 6-13,9-11 

caselle combinate 9-12, 19-12 

caselle di riepilogo 9-11 

penne 10-6 

pennelli 9-20, 10-9 

pulsanti strumento 8-50 

Web item 29-41 
StyleChanged, metodo 51-15 
StyleRule, proprieta 29-41 
Styles 

TApplication 14-6 
Styles, proprieta 29-41 
StylesFile, proprieta 29-41 
subcomponenti 

proprieta 47-10 
subscriber, oggetti 40-16 - 40-17 
Subtotals, proprieta 20-13 
suggerimenti 9-17, 19-34 
suporto tecnico 1-3 
SupportCallbacks, 

proprieta 29-18 
supporto al login 

WebSnap 34-26-34-33 
supporto all'installazione 1-3 
supporto alio sviluppo 1-3 
supporto decisionale, 
componenti 18-16, 20-1 - 20-21 

assegnazione dei dati 20-5 - 
20-7 

gestione della 
memoria 20-20 

runtime 20-19-20-20 
supporto, opzioni 1-3 
Suspend, metodo 11-12 



sviluppo, supporto 1-3 
switch, istruzioni 

valori case A-7 
Sybase, driver 

distribuzione 17-10 
Synchronize, metodo 11-5 
system resources, 

conserving 45-4 
System, pagina (Component 

palette) 5-7 

T 

tab, controlli 9-15 
owner-draw 6-12 

tabelle 22-24, 22-26 - 22-43 
asolalettura 22-40 
annidate 22-38-22-39 
basatesuBDE 24-2,24-5- 
24-9 

aggiornamento di 

record 24-8 
aggiornamento 

record 24-8 
aggiunta di record 24-8 
blocchi esclusivi 24-6 
cancellazione di 

record 24-8 
chiusura 24-5 
collegamento 24-5 
copia di record 24-8 
copia record 24-8 
diritti di accesso 24-6 
operazioni batch 24-8 - 

24-9 

ricerche basate su 
indice 22-29 
cancellazione 22-42 
creazione 22-40-22-42 

campi persistenti 22-41 

indici 22-41 
dbExpress 26-7-26-8 
definizione 22-40-22-41 
definizione di campi e indici 

precaricamento 22-41 
definizioni di campi e 

indici 22-40,22-41 
elenco 21-14 

griglie non-database 9-17 
indici 22-27-22-39 
inserimento di record 22-19 

- 22-20, 22-23 
intervalli 22-32-22-36 
ordinamento 22-27,26-7 
relazioni master/ 

detail 22-36 - 22-39 



ricerca 22-29-22-31 
sincronizzazione 22-43 
specifica del database 22-26 
svuotamento 22-42 - 22-43 
visualizzazione in 
griglie 19-18 
tabelle annidate 22-38 - 22-39, 

23- 27-23-28, 29-20 
tabelle dBASE 

accesso ai dati 24-9 
aggiunta di record 22-20 
tabelle detail annidate 
acquisizione su 
richiesta 28-6 
tabelle Paradox 

operazioni batch 24-55 
tabelle problem 24-54 
Table, marcatore HTML (</ 

TABLE>) 33-15 
TableAttributes, 
proprieta 33-20 
TableName, proprieta 22-40, 
26-7 

TableOfContents 7-34 
TableType, proprieta 22-40, 

24- 5 - 24-6 

Tabs, proprieta 9-15 
TabStopChanged, 

metodo 51-15 
TAction 8-22 
TActionClientltem 8-24 
TActionList 8-20,8-21 
TActionMainMenuBar 8-18, 

8-19, 8-20, 8-21, 8-23, 8-24 
TActionManager 8-18, 8-20, 

8-21 

TActionToolBar 8-18, 8-19, 8-20, 

8-21, 8-23 
TActiveForm 43-3,43-6 
TAdapterDispatcher 34-37 
TAdapterPageProducer 34-35 
TADOCommand 25-2,25-7, 

25- 9, 25-17-25-20 
TADOConnection 18-9, 21-1, 

25-2, 25-2 - 25-9, 25-10 
connessione a datastore 25-3 
-25-5 

TADODataSet 25-2, 25-9, 25-16 

- 25-17 
TADOQuery 25-2, 25-9 
SQL command 25-17 
TADOStoredProc 25-2, 25-9 
TADOTable 25-2, 25-9 
Tag, proprieta 23-13 
TApplication 7-29,7-36 
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Styles 14-6 
Tapplication 

eventi di sistema 51-13 
TApplicationEvents 8-2 
TASM, codice 

Linux 14-18 
TASPObject 42-2 
tasti acceleratori 9-6 
TAutoDriver 40-6,40-14 
tavolozze 50-5 - 50-6 

comportamento 
predefinito 50-6 

specifica 50-5 
TBatchMove 24-50-24-55 

gestione degli errori 24-54 - 
24-55 
TBCDField 

formattazione 
predefinita 23-16 
TBDEClientDataSet 24-2 
TBDEDataSet 22-2 
TBevel 9-20 
TBitmap 50-4 
TBrush 9-20 
tbsCheck, costante 8-50 
TByteDynArray 36-4 
TCalendar 55-1 
TCanvas 

utilizzo 4-21 
TCharProperty, tipo 52-8 
TClassProperty, tipo 52-8 
TClientDataSet 27-20 
TClientDataset 7-24 
TClientSocket 37-6 
TColorProperty, tipo 52-8 
TComlnterface 40-6, 40-14 
TComponent 3-4, 3-7, 45-5 

definizione 3-5 

interfacce 13-4, 13-5 
TComponentClass 45-14 
TComponentProperty, tipo 52-8 
TControl 3-8, 45-4, 48-5 

definizione 3-5 
TConvType values 4-28 
TConvTypelnfo 4-32 
TCoolBand 9-10 
TCoolBar 8-46 
TCP/IP 24-16, 37-1 

applicazioni multi-tier 29-10 
-29-11 

client 37-6 

connessione all'application 

server 29-25 
server 37-7 



TCRemoteDataModule 29-14, 

29-15 
TCurrencyField 
formattazione 
predefinita 23-16 
TCustomADODataSet 22-2 
TCustomClientDataSet 22-2 
TCustomContentProducer 33-1 
4 

TCustomControl 45-4 
TCustomEdit 14-8 
TCustomGrid 55-1, 55-3 
TCustomlniFile 4-12 
TCustomizeDlg 8-24 
TCustomListBox 45-3 
TDatabase 18-8, 21-1, 24-3, 
24-17 
DatabaseName, 
proprieta 24-3 
istanze temporanee 24-21 
interruzione 24-21 
TDataSet 22-1 

discendenti 22-2-22-3 
TDataSetProvider 28-1, 28-2 
TDataSetTableProducer 33-21 
TDataSource 19-3-19-5 
TDateField 

formattazione 
predefinita 23-16 
TDateTime, tipo 55-6 
TDateTimeField 
formattazione 
predefinita 23-16 
TDBChart, componente 18-16 
TDBCheckBox 19-2, 19-14 - 
19-15 

TDBComboBox 19-2, 19-11, 

19-11 - 19-12 
TDBCtrlGrid 19-3, 19-30 - 19-31 

proprieta 19-31 
TDBEdit 19-2, 19-9 
TDBGrid 19-2, 19-16 - 19-30 

eventi 19-29 

proprieta 19-22 
TDBGridColumns 19-17 
TDBImage 19-2,19-10-19-11 
TDBListBox 19-2, 19-11, 19-11 - 
19-12 

TDBLookupComboBox 19-2, 

19-11, 19-12-19-14 
TDBLookupListBox 19-2, 19-11, 

19-12 - 19-14 
TDBMemo 19-2, 19-9 - 19-10 
TDBNavigator 19-2, 19-31 - 

19-34, 22-6 



TDBRadioGroup 19-2, 19-15 
TDBRichEdit 19-3, 19-10 
TDBText 19-2, 19-8 - 19-9 
TDCOMConnection 29-24 
TDecisionCube 20-1, 20-5, 20-7 
-20-9 

eventi 20-7 
TDecisionDrawState 20-13 
TDecisionGraph 20-1, 20-2, 

20-13 - 20-19 
TDecisionGrid 20-1, 20-2, 20-11 
- 20-13 

eventi 20-13 

proprieta 20-12 
TDecisionPivot 20-1, 20-2, 20-10 

proprieta 20-10 
TDecisionQuery 20-1, 20-5, 20-6 
TDecisionSource 20-1, 20-9 - 
20-10 

eventi 20-9 

proprieta 20-9 
TDefaultEditor 52-16 
TDependency_object 7-9 
TDragObject 6-4 
TDragObjectEx 6-4 
TDrawingTool 10-13 
TEdit 9-1 

temporanei, file A-ll 
temporanei, oggetti 50-6 
TEnumProperty, tipo 52-8 
terminate con null, routine 4-25 
-4-26 

terminate, funzione 12-5 
Terminate, metodo 11-6 
Terminated, proprieta 11-6 
testo 

cancellazione 6-10 

controlli owner-draw 6-12 

copia, taglia, incolla 6-9 

in controlli 6-7 

internazionalizzazione 16-9 

lettura da destra a 
sinistra 16-6 

operazioni con 6-7 - 6-12 

ricerca di 9-3 

selezione 6-9, 6-9 

stampa 9-3 
testo statico, controllo 9-4 
testo, stream A-9 
TEvent 11-10 
TEventDispatcher 40-15 
Text, proprieta 9-3, 9-12, 9-17 
TextChanged, metodo 51-15 
TextHeight, metodo 10-5, 50-3 
TextOut, metodo 10-5, 50-3 
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TextRect, metodo 10-5, 50-3 
TextWidth, metodo 10-5, 50-3 
TField 22-1,23-1-23-29 
eventi 23-16-23-17 
metodi 23-17-23-18 
proprieta 23-1,23-11-23-16 
in esecuzione 23-13 
TFieldDataLink 56-5 
TFiler 4-3 

TFileStream 4-2,4-5 

I/O su file 4-5-4-7 
TFloatField 

formattazione 
predefinita 23-16 
TFloatProperty, tipo 52-8 
TFMTBcdField 

formattazione 
predefinita 23-16 
TFontNameProperty, tipo 52-9 
TFontProperty, tipo 52-9 
TForm 

proprieta della barra di 
scorrimento 9-5 
TFrame 8-14 
TGraphic 50-4 
TGraphicControl 45-4, 54-3 
THandleComponent 51-12 
THeaderControl 9-16 
this, argomento 45-17 
thread 11-1-11-15 

assegnazione dei nomi 11-13 
-11-15 

attesadi 11-10 
multipli 11-11 

attesa di eventi 11-10 

attivita 44-21 

BDEe 24-13 

blocco dell'esecuzione 11-8 
blocco di oggetti 11-8 
ciclo di messaggi e 11-5 
come evitare l'accesso 

simultaneo 11-8 
componenti di accesso ai 

dati 11-5 
conversione da senza nome a 

connome 11-13 
coordinamento 11-4,11-7- 

11-11 

CORBA 31-12-31-13 
creazione 11-12 
eccezioni 11-7 
esecuzione 11-12 
id 11-13 

inizializzazione 11-3 
interruzione 11-6, 11-12 



ISAPI/NSAPI, 
programmi 33-2, 33-18 

liberazione 11-3, 11-4 

limiti sul numero 11-12 

oggetti grafici 11-5 

priorita 11-1, 11-3 
ridefinizione 11-12 

servizio 7-7 

sezioni critiche 11-8 

spazio di processo 11-4 

thread della VCL 11-4 

uso di elenchi 11-5 

valori restituiti 11-10 

thread, modificatore 11-6 

thread principale della 
VCL 11-4 

evento OnTerminate 11-7 
Thread Status, casella 11-13 
thread, classi 

definizione 11-1 
thread, funzioni 11-4 
thread, oggetti 11-1 
thread, variabili 

CORBA 31-12 
ThreadID, proprieta 11-13 
throw, istruzione 12-2, 12-18 
THTMLTableAttributes 33-20 
THTMLTableColumn 33-20 
THTTPRio 36-17 
THTTPSoapCppInvoker 36-10, 
36-12 

THTTPSoapDispatcher 36-10, 
36-12 

TIBCustomDataSet 22-2 
TIBDatabase 18-9,21-1 
TickMarks, proprieta 9-6 
TickStyle, proprieta 9-6 
TIcon 50-4 
tie, classi 31-8 - 31-9 

VCLe 31-8 
tier 29-1 

TiledDraw, metodo 50-7 
TImage 

in controlli 8-16 
TImageList 8-50 
_TIME_, macro A-7 
timeout, eventi 11-11 
timer 5-7 
TIniFile 4-10,4-11 
TIntegerProperty, tipo 52-8 
TInterfacedObject 13-4, 13-5 
TInvokableClass 36-13 
tipi 

assegnazione di nomi 10-13 
Automation 41-16-41-17 



C++ e Object Pascal 13-20 

Char 16-3 

classi holder 36-6 

definiti dell'utente 54-4 

gestori di evento 48-3 

librerie di tipi 39-12 - 39-13 

MIME 10-23 

non specificati 13-17 

proprieta 47-2, 47-9, 52-9 

record di messaggio 51-7 

Web Services 36-4-36-10 

tipi character 16-3 

tipi definiti daU'utente 54-4 

tipi di campo 

conversione 23-17, 23-19 - 
23-21 

tipi di server 34-9 

tipi enumerati 47-2, 54-4 
costanti e 10-13 
dichiarazione 10-13, 10-14 

tipi enumerativi 

Type Library editor 39-10, 
39-17 

tipi non mappati 13-24 
tipi semplici 47-2 
tipi set 47-2 
tipo di dati Char 16-3 
Title, proprieta 

griglie dati 19-22, 19-23 
titoli delle colonne 9-16, 19-19, 
19-23 

TKeyPressEvent 48-3 

TLabel 9-4,45-4 

.TLB, file 38-19, 39-2, 39-21 

TLCDNumber 9-2 

TLIBIMP, strumento della riga 

comandi 38-20, 40-2, 40-6, 

41-15 
TListBox 45-3 

TLocalConnection 27-27, 29-5 
TMainMenu 8-20 
TMaskEdit 9-1 
TMemlniFile 4-10,4-11, 14-7 
TMemo 9-1 
TMemoryStream 4-2 
TMessage 51-5,51-7 
TMetafile 50-4 
Tmethod, tipo 51-12 
TMethodProperty, tipo 52-8 
TMTSASPObject 42-2 
TMtsDll 44-4, 44-27 
TMultiReadExclusiveWriteSync 

hronizer 11-9 
TNestedDataSet 22-39 
TNotifyEvent 48-7 
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TObject 3-4, 13-9, 13-23, 13-29, 
46-4 

definizione 3-5 
ToCommon 4-32 
TOleContainer 40-17-40-18 

Active Documents 38-15 
TOleControl 40-6,40-7 
TOleServer 40-6 
toolbars 

definizione 8-19 
Tools API 

wizard 58-3,58-3-58-7 
ToolsAPI, unit 58-2 
tool-tip help 9-17 
Top, proprieta 8-4,8-47 
TopRow, proprieta 9-18 
TOrdinalProperty, tipo 52-8 
TPageControl 9-16 
TPageDispatcher 34-37 
TPageProducer 33-14 
TPaintBox 9-20 
TPanel 8-46,9-14 
TPersistent 13-7 

definizione 3-5 
tpHigher, costante 11-3 
tpHighest, costante 11-3 
TPicture, tipo 50-4 
tpldle, costante 11-3 
tpLower, costante 11-3 
tpLowest, costante 11-3 
tpNormal, costante 11-3 
TPopupMenu 8-52 
-Tpp, opzione del linker 15-13 
TPrinter 4-26 

utilizzo 3-4 
TProperty Attributes 52-11 
TPropertyEditor, classe 52-8 
TPropertyPage 43-14 
tpTimeCritical, costante 11-3 
TQuery 24-2,24-9-24-12 

dataset decisionali e 20-5 
TQueryTableProducer 33-21 
track bar 9-5 
track bar orizzontali 9-6 
track bar verticali 9-6 
traduzione 16-9 
traduzioni in lingue 

straniere 16-1 
Transactional Data Module, 

wizard 29-15-29-16 
Transactional Object 

wizard 44-18-44-22 
transazionali, moduli dati 

classe di 
implementazione 29-15 



transazioni 18-5, 21-6 - 21-11 
ADO 25-6 - 25-7, 25-8 
ritenzione degli 

annullamenti 25-6 
ritenzione delle 
modifiche 25-6 
aggiornamenti in 

cache 24-35 
annidate 21-7 

conferma 21-9 
annullamento 21-9-21-10 
applicazione degli 

aggiornamenti 21-7, 29-18 
applicazioni multi-tier 29-18 

- 29-19 
atomicita 18-5,44-11 
attributi 44-12-44-13 
automatiche 44-14 
avvio 21-7-21-8 
BDE 24-31 - 24-33 

controllo 24-31 - 24-32 
implicite 24-31 
componenti transaction 21-8 
composte da piu 

oggetti 44-11 
conferma 21-8-21-9 
congruenza 18-5, 44-11 
contesti di oggetto 44-11 
controllate dal client 44-15 - 
44-16 

controllate dal server 44-16 
durabilita 18-5,44-11 
IAppServer 29-19 
isolamento 18-5,44-11 
livelli 21-10-21-11 
locali 24-33 
moduli dati 

transazionali 29-7, 29-16, 

29-18 - 29-19 
MTSeCOM+ 44-10-44-17 
oggetti transazionali 44-5, 

44-10 - 44-17 
sovrapposte 21-8 
su piu database 44-11 
tabelle locali 21-7 
termine 21-8 - 21-10, 44-13 - 

44-14 
timeout 44-17,44-28 
uso di comandi SQL 21-6 
utilizzo di comandi 

SQL 24-32 
transazioni a due fasi 29-18 
transazioni locali 24-33 
transazioni, livello di 
isolamento 21-10-21-11 



specifica 21-10 
transazioni locali 24-33 
TransformGetData, 

proprieta 30-9 
TransformRead, proprieta 30-8 
TransformSetParams, 

proprieta 30-10 
Transform Write, proprieta 30-8 
Transudation, proprieta 21-10 

transazioni locali 24-33 
transitorie, sottoscrizioni 40-16 
Transliterate, proprieta 23-13, 
24-51 

Transparent, proprieta 9-5 
trasferimento dei record 57-2 
trasformazione di stringhe di 

caratteri 16-2, 16-8, 16-10 
trasformazione in stringhe di 

caratteri 
conversioni 2 byte 16-3 
trasparenza, delle barre 

strumenti 8-50, 8-52 
TReader 4-3 
TReglniFile 14-7 
TRegistry 4-10 
TRegistrylniFile 4-10, 4-12 
TRegSvr 17-5,38-20 
TRemotable 36-7 
TRemoteDataModuleRegistrar 

29-9 
TRichEdit 9-1 
trigger 18-5 
trinagoli 10-12 

try, parola chiave 12-7 

try,blocco 12-2 
try, istruzione 12-11 
TScrollBox 9-5,9-15 
TSearchRec 4-8 
TServerSocket 37-7 
TService_object 7-9 
TSession 24-17-24-31 

aggiunta 24-28, 24-29 
TSetElementProperty, tipo 52-8 
TSetProperty, tipo 52-8 
TSharedConnection 29-30 
TSocketConnection 29-25 
TSpinEdit control 9-6 
TSQLClientDataSet 26-2 
TSQLConnection 18-9, 21-1, 

26-2 - 26-6 
collegamento 26-3 - 26-6 
monitoraggio dei 
messaggi 26-18 
TSQLDataSet 26-2, 26-6, 26-7, 

26-8 
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TSQLMonitor 26-18 - 26-19 
TSQLQuery 26-2, 26-6 
TSQLStoredProc 26-2, 26-8 
TSQLTable 26-2,26-7 
TSQLTimeStampField 
formattazione 
predefinita 23-16 
TStoredProc 24-2, 24-12 - 24-13 
TStream 4-2 

TStringList 4-16 - 4-21, 7-32 
TStringProperty, tipo 52-8 
TStrings 4-16-4-21 
TTabControl 9-15 
TTable 24-2, 24-5 - 24-9 

dataset decisionali e 20-6 
TTextBrowser 9-2 
TTextViewer 9-2 
TThread 11-2 
TThreadList 11-5,11-8 
TTimeField 

formattazione 
predefinita 23-16 
TToolBar 8-20, 8-46, 8-49 
TToolButton 8-46 
TTreeView 9-12 
TUpdateSQL 24-41 - 24-50 

provider e 24-11 
TWebActionltem 33-3 
TWebAppDataModule 34-2 
TWebAppPageModule 34-2 
TWebConnection 29-26 
TWebContext 34-36 
TWebDataModule 34-2 
TWebDispatcher 34-37, 34-41 
TWebPageModule 34-2 
TWebResponse 33-3 
TWidgetControl 14-6 

definizione 3-5 
TWinControl 3-9, 13-9, 13-11, 
16-9, 45-4, 48-5 

definizione 3-5 
TWMMouse, tipo 51-7 
TWriter 4-3 

TWSDLHTMLPublish 36-10, 
36-16 

TWSDLHTMLPublisher 36-12 
TXMLDocument 35-3 - 35-4, 
35-9 

TXMLTransform 30-6 - 30-8 
documenti sorgente 30-6 
TXMLTransformClient 30-9 - 
30-11 
parametri 30-10 
TXMLTransformProvider 28-1, 
28-2, 30-8 - 30-9 



Type Library editor 38-18, 39-2 
- 39-20 
aggiornamento 39-19 
aggiunta di interfacce 39-14 
alias 39-10 

aggiunta 39-18 
apertura di librerie 39-14 
application server 29-17 
barra di stato 39-5 
barra strumenti 39-3 - 39-5 
CoClass 39-10 

aggiunta 39-16-39-17 
collegamento di 
attributi 43-12 
COM+, pagina 44-5 
definizioni dei tipi 39-10 - 

39-11 
dispinterface 39-10 
elementi 39-8-39-11 
caratteristiche 
comuni 39-8-39-9 
interfacce 39-9-39-10 

modifica 39-15-39-16 
messaggi di errore 39-5, 39-8 
metodi 

aggiunta 39-15-39-16 
moduli 39-11 

aggiunta 39-18-39-19 
Object list, pannello 39-5 
pagina COM+ 44-10 
pagina Text 39-8, 39-16 
pagine di informazioni di 

tipo 39-6-39-8 
parti 39-3-39-8 
proprieta 

aggiunta 39-15-39-16 
record e union 39-11 

aggiunta 39-18 
salvataggio e registrazione di 
informazioni di tipo 39-19 
- 39-20 
selezione di elementi 39-5 
tipi enumerati 39-10 
aggiunta 39-17 
type, parola riservata 10-13 
typedef, da Object Pascal a 
C++ 13-16 

u 

UCS, standard 14-21 
UDP, protocollo 37-1 
Unassociate Attributes, 

comando 23-15 
underflow, errori 
math, funzioni A-8 



UndoLastChange, metodo 27-6 
unexpected, funzione 12-5 
UnhandledExceptionFilter, 

funzione 12-7 
Unicode, caratteri 16-3, 16-4 

stringhe 4-21 
UniDirectional, proprieta 22-51 
unidirezionali, cursor 22-51 
union 

accesso A-5 
membri con tipi 
differenti A-5 
Type Library editor 39-11, 
39-18 

unit 

aggiunta di 

componenti 45-13 
C++Builder 45-12 
CLX 14-10-14-12 
esistenti 

aggiunta di un 
componente 45-12 
VCL 14-10-14-12 
unit di base 4-29,4-31 
unita termometriche 4-30 
unita, in conversione 4-29 
Unlock, metodo 11-8 
UnlockList, metodo 11-8 
UnRegisterTypeLib, 

funzione 38-19 
Update SQL editor 

SQL, pagina 24-43 
Update SQL, editor 24-43 - 
24-44 

Options, pagina 24-43 
UPDATE, istruzioni 24-42, 

24- 46, 28-10 

update, oggetti 24-41 - 24-50, 
27-20 

esecuzione 24-48-24-49 
istruzioni SQL 24-42 - 24-46 
parametri 24-44-24-45, 

24-48, 24-49 - 24-50 
provider e 24-11 
query 24-49-24-50 
utilizzo di piu oggetti 24-46 

-24-49 

UpdateBatch, metodo 14-29, 

25- 13, 25-14 
UpdateCalendar, metodo 56-4 
UpdateMode, proprieta 28-10 

dataset client 27-23 
UpdateObject, metodo 43-15, 
43-16 
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UpdateObject, proprieta 24-11, 

24-34, 24-42, 24-47 
UpdatePropertyPage, 

metodo 43-15 
UpdateRecordTypes, 

proprieta 14-29, 24-34, 27-20 
UpdateRegistry, metodo 29-9 
UpdatesPending, 

proprieta 14-29,24-34 
UpdateStatus, proprieta 14-29, 

24-34, 25-12, 27-20, 28-9 
UpdateTarget, metodo 8-31 
up-down controls 9-6 
up-down, controlli 9-6 
URI e URL 32-4 
URL 32-4 

connessioni Web 29-26 
eURI 32-4 
indirizzilP 37-4 
librerie javascript 29-34, 

29-35 
nomi di host 37-4 
Web browser 32-5 
URL, proprieta 29-26, 29-27, 

33-9, 36-18 
URLs 

connessioni SOAP 29-27 
Use CORBA Object, 

wizard 31-15 
user list service 34-11, 34-27 
uses, clausola 

aggiunta di moduli dati 7-24 
uuid, argomento 13-3 

V 

valori 47-2 

booleani 47-2, 47-12, 56-4 

collaudo 47-7 

dati predefiniti 19-11 

predefiniti delle 
proprieta 47-7,47-12- 
47-13 

proprieta predefinita 
ridefinizione 53-3, 53-4 

sequenziali 10-13 
valori additivi 

crosstab 20-3 
valori booleani 47-2, 47-12, 56-4 
valori di consultazione 19-19 
valori di riepilogo 

aggregati di 
manutenzione 27-14 

cubi decisionali 20-20 

grafici decisionali 20-15 
valori in virgola mobile A-4 



caratteri di punto 
decimale A-7 
valori logici 19-2, 19-14 
valori sequenziali, assegnazione 

a costanti 10-13 
Value, proprieta 
aggregati 27-14 
campi 23-19 

parametri 22-48, 22-54, 22-55 
ValueChecked, proprieta 19-14 
Values, proprieta 

gruppi di pulsanti di 
opzione 19-15 
ValueUnchecked, 

proprieta 19-14,19-15 
valuta 

esempio di conversione 4-32 
formati 16-10 

internazionalizzazione 16-10 
var, parametri 13-17 
variabili di thread 11-5 
variabili locali al thread 11-5 

evento OnTerminate 11-7 
VCL 7-13,45-1-45-2 

classi di eccezioni 12-17 

costruzione di oggetti 13-9 

eCLX 14-5-14-8 

gestione delle 
eccezioni 12-15 

panoramica 3-1 - 3-2 

ramo Tcomponent 3-7 

ramo Tcontrol 3-8 

ramo Tobject 3-6 

ramo Tpersistent 3-6 

ramo TWinControl 3-9 

supporto del linguaggio 
C++ 13-1-13-31 

thread principale 11-4 

unit 14-10-14-12 
VCL, applicazioni 

porting in Linux 14-2 - 14-16 
vcl60.bpl 15-1, 15-10, 17-6 

penwin.dll 15-13 
VCLCONTROLJMPL, 

macro 43-3, 43-6 
VendorLib, proprieta 26-4 
verifica 

componenti 45-17, 45-19, 
57-7 

valori 47-7 
VertScrollBar 9-5 
video analogici 10-34 
video cassette 10-34 
video clip 10-31 
video, filmati 10-33 



ViewStyle, proprieta 9-13 
vincoli 

controlli 8-4-8-5 

data 

importazione 27-32 
dati 23-22-23-23 

creazione 23-22-23-23 
dataset client 27-7 - 27-8, 

27- 32 - 27-33 
disattivazione 27-32 
importazione 23-23, 

28- 13, 28-14 
violazione dell'integrita 24-54 
violazioni di chiave 24-54 
virgola mobile, valori 

specificatori di formato A-3 
virtual 

metodi 49-4 

proprieta come 47-2 

parola chiave 46-10 
virtuali 

funzioni 13-12 

metodi 

editor di proprieta 52-9 

metodi di classe 13-15 

tabella dei metodi 46-10 
Visible, proprieta 3-2 

barre strumenti 8-53 

campi 23-13 

coolbar 8-53 

menu 8-44 
VisibleButtons, proprieta 19-32, 
19-33 

VisibleChanged, metodo 51-15 
VisibleColCount, proprieta 9-18 
VisibleRowCount, 

proprieta 9-18 
viste ad albero 9-12 

owner-draw 6-12 
VisualCLX 

definizione 14-5 

package 15-10 
visualizzazione di script 34-35 
visualizzazione tabellare 

(griglie) 9-17 
VisualSpeller Control 17-5 
voci di menu 8-34 - 8-37 

aggiunta 8-34,8-44 

annidamento 8-37 

assegnazione dei nomi 8-34, 
8-43 

barre di separazione 8-36 
cancellazione 8-35, 8-40 
definizione 8-32 
editing 8-39 
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impostazione delle 

proprieta 8-39-8-40 
lettere sottolineate 8-36 
raggruppamento 8-36 
segnaposti 8-40 
spostamento 8-38 
vtable 38-5 

classi creatore e 40-6, 40-13 - 

40-14 
e dispintrface 39-10 
interfacce duali 41-13 
librerie di tipi e 38-18 
puntatore di interfaccia 

COM 38-5 
wrapper di componenti 40-7 

w 

W3C 35-2 

WaitFor, metodo 11-10, 11-11 
WantReturns, proprieta 9-3 
WantTabs, proprieta 9-3 
controlli memo data- 
aware 19-9 
controlli rich edit data- 
aware 19-10 
.wav, file 10-34 
wchar_t widechar 14-21 
wchar_t, costante di 

carattere A-4 
Web application 

debugger 32-10, 33-2, 34-9 
Web application, moduli 34-3, 

34-3 - 34-4 
Web application, oggetto 33-3 
Web Broker 7-17 
Web Broker, applicazioni 
server 32-1 - 32-3, 33-1 - 33-21 
accesso a database 33-18 
aggiunta ai progetti 33-3 
architettura 33-3 
creazione 33-1 - 33-3 
creazione di risposte 33-8 
gestione delle connessioni ai 

database 33-18 
gestione eventi 33-5, 33-7, 
33-9 

interrogazione di 

tabelle 33-21 
invio di dati a 33-11 
invio di file 33-13 
modelli 33-2 
modelli di risposta 33-14 
panoramica 33-1 - 33-4 
Web dispatcher 33-4 
Web browser 



URL 32-5 
Web data, moduli 34-2, 34-3 

struttura 34-5 
Web Deployment Options, 
finestra di dialogo 43-18 
Web dispatcher 

gestione delle richieste 33-3 
oggetti a dispatch 
automatico 29-37 
Web module 33-4 
Web page editor 29-39 - 29-40 
Web page, moduli 34-2, 34-4 - 
34-5 

Web server 32-1 - 32-12 

debug 33-2 

tipi 34-9 
Web server, applicazioni 7-17, 
32-12 

debug 32-9 - 32-12 

multi-tier 29-33-29-43 

panoramica 32-7-32-12 

standard 32-3 

tipi 32-7 

ubicazione delle risorse 32-4 
Web Service Definition 
Language Vedi WSDL 
Web Services 36-18 

aggiunta 36-12-36-14 
classi di 
implementazione 36-12 - 
36-14 
classi holder 36-6 
client 36-17-36-18 
contesto dati 36-8 
eccezioni 36-15 - 36-16 
importazione 36-14 - 36-15 
namespace 36-3 
registrazione delle classi di 

implementazione 36-13 
scrittura di server 36-10 - 

36-16 
server 36-10-36-17 
tipi complessi 36-4 - 36-10 
tipi enumerati 36-6 
tipi scalari 36-4 
wizard 36-11-36-15 
Web Services, 

importatore 36-14 
Web, applicazioni 
ActiveX 38-14, 43-1 
ASP 38-14, 42-1 
distribuzione 17-10 
Web, connessioni 29-11,29-26 
Web, distribuzione 43-17- 
43-19 



applicazioni multi-tier 29-33 
Web, moduli 34-2, 34-2 - 34-5 

tipi 34-2 
Web, moduli dati 34-5 
Web, pagina 

InternetExpress, produttori 
dipagine 29-39-29-43 
Web, pagine 32-5 
WebDispatch, proprieta 29-37, 
36-12 

WebPageltems, proprieta 29-39 
WebServices, pagina 

(Component palette) 29-2 
WebServices, pagina (New 

Items, finestra di dialogo) 29-2 
WebSnap 32-1-32-3 

diritti di accesso 34-31 - 

34-33 
esempi di script lato 

server B-19 
esercizio 34-12-34-24 
login obbligatorio 34-30 - 
34-31 

oggetti script globali B-14 
pagine di login 34-28 - 34-30 
scripting lato server 34-33 - 

34-36, B-l - B-39 
supporto al login 34-26 - 

34-33 

wide character, costanti A-4 
widechar 14-21 
widestring 14-21 
widget 3-9 

creazione 14-13 

e controlli Windows 14-6 
WidgetDestroyed, 
proprieta 51-14 
Width, proprieta 8-4, 9-17 

colonne delle griglia 
dati 19-18 

grigliedati 19-22 

penne 10-6 
Win 3.1, pagina (Component 

palette) 5-8 
WIN32 14-19 

Win32, pagina (Component 

palette) 5-7 
Win-CGI, applicazioni 32-6, 

32-7 

creazione 33-2, 34-9 
file .ini 32-7 
Windows 

contesti di dispositivo 45-7, 
50-1 
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controlli, derivazione di 

classe 45-4 
eventi 48-4 
finestre di dialogo 

comuni 57-2 
creazione 57-2 
esecuzione 57-5 
funzioni API 45-4, 50-1, 51-2 
Graphics Device Interface 

(GDI) 10-1 
messaggi 51-3 
sistema di messaggi 51-1 - 

51-11 

wininet.dll 29-26,29-27 

wizard 7-25 

Active Server Object 38-22 
Active Server Objects 42-2 - 

42- 3 

ActiveForm 38-23,43-6- 

43- 7 

COM 38-20-38-25,41-1 
COM+ Event object 38-23 
COM+ Event subscriber, 

oggetto 44-25 
COM+ Event, oggetto 44-24 

- 44-25 
Component 45-9 
Console Wizard 7-4 
controlli ActiveX 38-22, 43-4 

-43-6 
CORBA client 31-14 
CORBA Object 31-7, 31-14 
CORBA Server 31-5 
creazione 58-2, 58-3 - 58-7 
debug 58-11-58-12 
installazione 58-7, 58-23 - 

58-25 

libreria ActiveX 38-23 
oggetti Automation 38-22, 

41-4 - 41-9 
oggetti COM 38-22, 39-14 
oggetto COM 41-3 - 41-4, 

41-5 - 41-9 
oggetto transazionale 38-23, 

44- 18 - 44-22 

pagina di proprieta 38-23 
Property Page 43-14 - 43-15 
Remote Data Module 29-14- 

29-15 
Resource DLL 16-11 
risposta agli eventi 

dell'IDE 58-19 
SOAP Data Module 29-16- 

29-17 
tipi 58-3 



Tools API 58-3 
Transactional Data 

Module 29-15-29-16 
Type Library 38-23, 39-13 - 

39-14 

Use CORBA Object 31-15 
Web Services 36-11 - 36-15 
XML Data Binding 35-6 - 

35- 10 

WM_APP, costante 51-7 
WMJCEYDOWN, 
messaggio 56-9 
WM_LBUTTONBUTTON, 

messaggio 56-9 
WM_MBUTTONDOWN, 

messaggio 56-9 
WM_PAINT, messaggi 10-2 
WM_RBUTTONDOWN, 

messaggio 56-9 
WM_SIZE, messaggio 55-4 
WndProc, metodo 51-3, 51-5 
word, allineamento A-6 
Wordwrap, proprieta 6-7, 9-3 

controlli memo data- 
aware 19-9 
Wparam, parametro 51-10 
Wrap, proprieta 8-50 
Wrapable, proprieta 8-50 
wrapper 45-5, 57-2 

Vedi anche wrapper di 
componenti 

inizializzazione 57-4 
wrapper di componenti 

ActiveX, controlli 40-5 

COM, oggetti 40-2 
Write By Reference 

proprieta di interfaccia 
COM 39-9 
Write, metodo 

TFileStream 4-2 
write, metodo 47-7 
write, parola riservata 47-9, 54-5 
WSDL 36-2 

file 36-16 

importazione 36-3, 36-14 - 

36- 15, 36-17 
pubblicazione 36-16 - 36-17 

WSDL administrator 36-17 
WSDL, publisher 36-12 
WSDLIMP 36-15 

X 

XDR,file 35-2 
Xerox Network System 
(XNS) 37-1 



.xfm, file 14-2 
XML 30-1,35-1 

applicazioni database 30-1 - 
30-11 

dichiarazione del tipo di 

documento 35-2 
istruzioni di 

elaborazione 35-1 
mappatura 30-2-30-4 

definizione 30-4 
parser 35-2 
SOAP 36-1 
XML Data Binding, wizard 35-6 

- 35-10 
XML, broker 29-34, 29-36 - 

29- 38 

messaggi HTTP 29-37 
XML, documenti 30-1, 35-1 - 
35-10 
attributi 30-5,35-5 
componenti 35-3 - 35-4, 35-9 
conversione in pacchetti 

dati 30-1 - 30-8 
generazione di interfacce 

per 35-6 
mappatura di nodi a 

campi 30-2 
nodi 35-2, 35-4 - 35-6 
nodi figlio 35-5 - 35-6 
nodo radice 35-4, 35-7, 35-9 
proprieta dei nodi 35-6 
pubblicazione di 

informazioni database 30-9 
trasformazione di file 30-1 
XML, file 25-15 
XML, schemi 35-2 
XMLBroker, proprieta 29-40 
XMLDataFile, proprieta 28-2, 

30- 8 

XMLDataSetField, 

proprieta 29-40 
XMLMapper 30-2, 30-4 - 30-6 
XSD, file 35-2 
XSLPageProducer 34-5 

Y 

Year, proprieta 55-6 
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